Context: from one chat to a whole org

Every turn the model sees a stack of context. Some of it lives only for the next reply. Some persists across your sessions. Some is shared across your whole team or organization. This page is the one to read if you want to understand the full ladder — from "what the model remembered five minutes ago" up to "the policy our entire company injects into every agent" — and how to move information up that ladder deliberately.

The elevation ladder

Five rungs, each broader in scope and more durable than the last:

Rung	Lives	Lifetime	Visible to	Where it's authored
1. Working memory	The current session's recent messages	Until session ends	Just this session	Implicit — it's whatever you've typed
2. Compacted history	The session's summarized older turns	Until session ends	Just this session	Auto-written by Kenaz; user-editable
3. Long-term memory	Pinned Chunks on your local store	Forever (or until you delete)	Sessions matching the chunk's scope	Right-click in chat → Remember this
4. Personal context pack	A YAML+Markdown pack on your machine	Forever; portable across machines	Every session that pack scopes to	Hand-authored or promoted from memory
5. Team / org context pack	A signed pack distributed via the bundle system	Forever; everyone on the team gets it	Every session at every teammate that the pack scopes to	Authored by a team member, signed, published

Rungs 1 and 2 together are what most people mean by "the conversation." Rung 3 is the Memory view (Memory & compaction). Rungs 4 and 5 are context packs — the rest of this page.

Why two systems (memory + packs)?

They're shaped for different jobs.

• Memory is a retrieval system. You pin a fact ("our staging DB is at staging.db.example.com"). It gets embedded. The model pulls it back into context only when a future turn looks semantically related. Good for facts you might need; bad for things that should always be true.
• Context packs are an injection system. The pack defines content that goes into the system prompt of every matching session — no retrieval, no maybe. Good for "every session in this org should know our coding style and never use AWS regions outside us-east-2"; bad for facts that don't need to be present every single turn.

A healthy team workflow uses both: memory for the long tail of project trivia an individual contributor accumulates, packs for the constant truths that everyone needs every time.

Context packs — the format

A pack is a directory or a single archive containing:

my-pack/
  pack.yaml             # metadata + scope rules
  context/
    coding-style.md     # injected as a system-prompt section
    glossary.md
    architecture.md
  overrides/
    no-aws-us-east-1.md # an override that beats lower-tier packs

pack.yaml:

id: acme-engineering
version: 2026.05.04+rev3
tier: team           # personal | team | org
display_name: Acme Engineering
description: Engineering-wide conventions, glossary, and architectural guardrails.

# Which sessions this pack applies to. Empty = applies to every session.
scope:
  workflow: ["engineering", "review", "code-gen"]   # any-of
  agent: []                                         # any-of (empty = any)
  role: ["engineer", "tech-lead"]                   # any-of
  project_glob: ["acme-*"]                          # any-of, glob match

# Files in context/ are concatenated in this order.
include:
  - context/coding-style.md
  - context/glossary.md
  - context/architecture.md

# Overrides are merged last and beat anything else with the same heading.
overrides:
  - overrides/no-aws-us-east-1.md

# Soft cap on injected size. Hard cap is enforced by Kenaz at 64 KB
# per pack to protect the system-prompt budget.
max_bytes: 16384

Each .md file is plain Markdown. Whatever you write becomes part of the system prompt for matching sessions, prefixed with a section header that includes the pack's display name so the model knows where the guidance came from.

The merge engine

When a session starts, Kenaz resolves all packs that match the session's scope and merges them in tier order:

org packs   (broadest, weakest)
  ↓ merged
team packs
  ↓ merged
personal packs
  ↓ merged
overrides   (strongest)
  ↓
final injected context  ← system prompt

Wider tiers go first; narrower tiers can overwrite. That's how a personal preference ("call me by my first name") can shadow an org-wide tone guideline; an overrides/ block in any pack can shadow the same heading in any other pack at the same or lower tier.

The merge is by Markdown heading (## / ###). Two packs that both contain ## Coding style produce one ## Coding style section in the final injected text — the higher-tier pack's content wins; the lower-tier pack's content is dropped (not merged inside).

If a conflict can't be resolved (two same-tier packs disagree at the same heading and neither is an override), Kenaz fails closed: the session shows a yellow banner "context conflict — resolve in Settings → Contexts" and no pack is injected until the conflict is fixed. This is intentional — silent conflicts are how shared-context systems lie to people.

Distributing a pack to a team

Three flavors, in order of how official your team is about it:

A. Git (simplest)

Pack lives in a repo. Teammates clone it and point Kenaz at the directory:

Settings → Contexts → Sources → Add directory → ~/code/acme-context.

Kenaz watches the directory; pushes to the repo land in everyone's session injection on the next chat turn (with a small "context updated" toast).

Suitable for: a small team that already has good Git hygiene; no signing, no granular scoping by role beyond what's in the pack.yaml.

B. The bundle system (recommended for teams ≥ 5)

Kenaz packs are first-class Kenaz bundles — content-addressed archives signed by the publishing team. Bundles are how Kenaz already distributes provider profiles, slash commands, and custom MCP recipes; context packs reuse the same plumbing.

Author flow:

1. kenaz bundle init my-context-pack in your pack directory.
2. Edit bundle.yaml to set kind: context, point at your pack.yaml, list the maintainers' public keys.
3. kenaz bundle sign --key team@acme.example (uses the team's Ed25519 signing key, generated and stored in the secret store on the publisher's machine).
4. kenaz bundle publish — pushes to your team's bundle registry (an HTTP endpoint you run, or the hosted Kameas Bundle Hub if you've opted in).

Subscriber flow:

1. Settings → Contexts → Sources → Add bundle subscription → paste the registry URL.
2. The first time a subscription is added, Kenaz prompts to trust the publisher's signing key. Approve it once.
3. New versions auto-pull (with a configurable update cadence) and get verified against the trusted key before they're applied. Failed verification → the session uses the previously-cached version, with a banner.

Bundles get you signing, content-addressed integrity (every snapshot has a hash; tampering is detectable), and a real audit trail of which version of the pack was active when a given turn happened.

C. Org-wide rollout

For full-organization packs (tier: org), the bundle approach is the same — but you'll typically also want:

• Mandatory subscription — managed via a small allowlist file at the org level that Kenaz reads at first launch. Once on the allowlist, the org pack can't be unsubscribed by individual users (only marked "acknowledged" so the session banner stops nagging).
• Versioned with a deprecation window — when you publish an org pack v2, v1 stays available for a configurable grace period so teams aren't broken by a single bad rollout.
• Audited globally — every change to the org pack writes an org_pack.published event to the audit log of every machine that picks it up. Useful evidence for compliance.

Suitable for: a security team that needs to land a "never run shell commands that touch prod-* buckets" rule across every engineer; a legal team distributing a privilege-marker pack so no agent generates content that should be attorney-client privileged.

Scoping (workflow / agent / role / project)

A pack's scope block declares which sessions it applies to. All listed dimensions are AND'd; within a dimension, values are OR'd.

Field	What it matches
workflow	The active workflow / slash-command class. Common values: chat, code-gen, review, agentic, ops. Set per-session in the chat header.
agent	The named agent profile, if you've set one. Lets you scope packs to e.g. a customer-support agent without affecting a coding-assistant agent.
role	A free-form role string per user. Set in Settings → User profile → Role (or pushed via SSO claim if your team uses Kenaz with external identity).
project_glob	Globs against the active project's name. acme-* matches every project starting with acme-.

Empty arrays mean "any value matches." Leaving the whole scope block off means the pack is global to the user/team/org subscribing to it.

Practical examples:

• A frontend team's pack scoped to workflow: ["code-gen", "review"] so it only ships during work, not during open-ended chat.
• A compliance pack scoped to role: ["external-contractor"] so it lights up for contractors and stays out of full-time employees' way.
• A project-specific architecture pack scoped to project_glob: ["acme-billing-*"].

Promoting up the ladder

The whole point of having a ladder is being able to climb it deliberately. Kenaz makes each step a one-click action:

Compacted history → long-term memory

In the Memory view, hover any line of a [Summary] card → Pin to memory. Pick a scope (session / project / global). The line becomes a Chunk and survives the session.

Long-term memory → personal context pack

Memory view → multi-select chunks → Promote to context pack. Kenaz drops the selected chunks into a draft pack at ~/.config/kaneaz-harness/contexts/personal/<draft-name>/, opens it in the contexts editor, and shows a preview of how the merged context will change for matching sessions.

Use this when you notice you're pinning the same kind of fact over and over — that's a sign it should be present every turn, not retrieved on match.

Personal pack → team pack

Settings → Contexts → personal pack → … → Open in editor → Promote tier. Changes tier: personal to tier: team, prompts for the team registry to publish to, and walks you through signing and pushing.

The original personal pack stays on your machine with a [promoted to team:acme-engineering] marker so you don't accidentally edit it (your changes wouldn't reach teammates). To make further changes, edit the team pack and re-publish.

Team pack → org pack

Same path, requires org-publish permission on the bundle registry. Most teams don't need this; org packs are reserved for genuinely organization-wide truths (compliance rules, security posture, brand voice) where local override is mostly undesirable.

Snapshots, replay, and "what was the model told?"

Every session takes a content-addressed context snapshot at start: a hash of the merged pack content, plus the version IDs of every pack that contributed. The snapshot ID is recorded in the audit log alongside the session, and lands on every prompt sent to the provider.

This means:

• You can answer "what context did the model see when it produced this response?" months later by looking at the audit log entry, finding the snapshot ID, and asking Kenaz to reconstruct it (kenaz contexts replay <snapshot-id>).
• You can compare two snapshots — useful when a session that worked yesterday goes weird today (kenaz contexts diff <id1> <id2>).
• A breaking pack rollout is reversible: pin everyone to the previous snapshot ID until the new pack is fixed.

For compliance-heavy contexts (legal review, regulated industries), the snapshot is the load-bearing artifact — it proves what the model knew, signed by the publishing team's key, with an audit log entry timestamped by your local machine. Pair it with the audit log export and you have a tamper-evident record of every model decision and its surrounding context.

Privacy

What leaves your machine, by tier:

Tier	Goes to provider on every turn?	Synced anywhere?
Working memory (session messages)	Yes — that's the conversation	No
Compacted history	Yes — as part of the assembled prompt	No
Long-term memory chunks (when retrieved)	Yes — when a chunk's similarity threshold is met for the turn	No
Personal context pack	Yes — injected into the system prompt	No
Team / org context pack	Yes — injected into the system prompt	Yes — pulled from the bundle registry on update; identical across every subscriber

Packs themselves are visible to anyone subscribed. Don't put secrets in packs (API_KEY=…, customer data, etc.). The secret store is the right place for those; packs are for shared guidance.

Practical recipes

• A team coding-style pack — tier: team, scope unset (applies everywhere), content covers naming conventions, error-handling patterns, framework preferences. Tier so personal preferences (like "call me Alex") still override.
• A compliance "do not" pack — tier: org, scope unset, content is a list of forbidden actions. Use overrides/ so even teams that have their own pack can't accidentally weaken it.
• A per-project architecture brief — tier: team, scope project_glob: ["billing-*"], content explains the architecture decisions a new contributor needs to know. Edit when the architecture changes; everyone picks up the next version.
• A personal "voice" pack — tier: personal, scope workflow: ["chat"], content sets your preferred tone and what topics you don't want unsolicited advice on. Stays on your machine; never shared.
• A regulated-industry signed pack — tier: org, signed by the compliance team, includes a snapshot ID requirement so every session's audit log proves which version was active.

Comparison cheat sheet

You want…	Use…
The model to remember a fact you might need later	Long-term memory (pin a chunk)
The model to always know something every turn	A context pack (auto-injected)
Just yourself to have it	Personal pack
Your team to have it	Team pack via bundle
Everyone in the org to have it	Org pack via bundle, mandatory subscription
To roll back a bad change	Snapshot pinning
To prove what the model was told	Snapshot ID + audit log
To stop a teammate from accidentally weakening a rule	overrides/ block + higher tier