agent A wrote "bullish."
agent B wrote "neutral — reassessing."
agent C read the result and made a decision.
nobody told agent C there was a disagreement.
this is a post-mortem.
Policy-enforced state and memory for agent teams.
Every agent has a scope. Ambit enforces it.
Every agent memory tool helps your agents remember more. They compete on retrieval quality, semantic search, cross-session recall, and how many benchmarks they've published this week.
None of them care what an agent is allowed to remember. Or surface it when that boundary gets crossed.
This produces two failure modes that are invisible until their consequences appear somewhere downstream:
Contention. Two agents write conflicting values to the same key. Last write wins. Neither agent knows. A third agent reads the result and acts on it. The output is wrong. There is no error message. You find out later, in the worst possible way.
Bleed. An agent working on Project B recalls a memory from Project A. The memory is plausible. The agent uses it. The output is subtly wrong. You find out three steps later, or during a review, or not at all.
Ambit surfaces both. Before they become your problem.
Ambit is a namespaced store where every namespace has a declared policy:
shared — multiple agents should converge on this value. Ambit versions every write, tracks who wrote it relative to which session, and emits a contention event when two agents write conflicting values within a configurable window. You find out immediately. The agents do not get to quietly disagree.
isolated — each agent keeps its own values in this namespace. Ambit enforces read boundaries by agent, project, or session, and emits a bleed event when an agent reads something it has no business reading. The memory stays where it belongs.
Both modes log agent identity, session ID, version, and timestamp on every entry. Every read and write is attributed. Every violation is named. Nothing is swallowed silently.
Not a retrieval tool. Ambit does not do semantic search, RAG, or vector embeddings. Use mem0, agentmemory, Letta, or any retrieval tool you already have. They help agents remember more. Ambit ensures what gets remembered stays within its declared boundary. These are different problems and they compose.
Not a database. Entries are YAML files on disk. Readable, portable, git-friendly, survives a restart. Optional SQLite backend for teams who outgrow flat files.
Not cloud-dependent. Fully self-hosted. No API keys, no vendor, no pricing page to squint at.
Not a framework. A primitive. Works alongside any agent runtime.
pip install agentambit
ambit init --workspace /path/to/workspace
# Declare a shared namespace (agents converge — contention detected)
ambit namespace create market-state --policy shared --agents warren,qin
# Declare an isolated namespace (agents stay separate — bleed detected)
ambit namespace create project-memory --policy isolated --agents warren,qin,tony
# Write a value
ambit set market-state/btc-thesis "Bullish — momentum confirmed" --agent warren
# Read a value
ambit get market-state/btc-thesis --agent qin
# Something went wrong — what happened?
ambit violations --since-hours 24
# Full audit trail
ambit audit --namespace market-state --since 7For values multiple agents should agree on: pipeline status, task flags, shared research conclusions, configuration.
namespaces:
market-state:
policy: shared
agents: [warren, qin, tony]
contention_window_sec: 300
on_contention: emit # emit | block | logWhen two agents write different values to the same key within the window:
VIOLATION [contention] market-state/btc-thesis
written by: warren @ 07:45:12 → "Bullish"
written by: qin @ 07:46:03 → "Neutral — reassessing"
window: 51s
action: emitted
Start with emit. Promote to block once you trust the declarations. The graduation path is intentional.
For values that should stay within an agent or project: session notes, working memory, project-specific context, anything that has no business crossing a boundary.
namespaces:
project-alpha-memory:
policy: isolated
scope_by: agent # agent | project | session
agents: [warren]
on_bleed: emitWhen an agent reads something outside its declared scope:
VIOLATION [bleed] project-alpha-memory/investment-thesis
written by: warren (project: alpha)
read by: warren (project: beta) ← out of scope
action: emitted
Zero dependencies. Fails silently if Ambit isn't running. Your agent will not crash because someone forgot to start the state registry. We've been there.
from agentambit.sdk import ambit
# Configure once at session start
ambit.configure(
agent_id="warren",
session_id=os.environ.get("SESSION_ID", ""),
project_id="alpha"
)
# Write and read
ambit.set("market-state/btc-thesis", "Bullish — momentum confirmed")
thesis = ambit.get("market-state/btc-thesis")
# Explicitly assert scope (surfaces in audit — useful for high-stakes namespaces)
ambit.assert_scope("project-alpha-memory")
# Check your own violations
recent = ambit.violations(namespace="market-state", since_hours=1)File (default): Entries are YAML. Human-readable, git-friendly, zero dependencies. Violation records are their own files. Audit log is JSONL. Everything survives outside a database.
.ambit/
namespaces/market-state/btc-thesis.yaml ← versioned entry with full history
violations/abc123.yaml ← every violation, named and dated
audit/2026-06-26.jsonl ← every read and write, attributed
archive/2026-05/... ← expired entries, not deleted
SQLite (optional): When you want to ask questions like "which agent wrote to market-state most often in the last 30 days without a contention event."
storage:
backend: sqlite
db_path: .ambit/ambit.dbambit query --namespace market-state --agent warren --since 7d
ambit query --violations --policy shared --since 24hkey: btc-thesis
namespace: market-state
policy: shared
current_value: "Bullish — momentum confirmed"
current_version: 3
agent_id: warren
session_id: run_20260626_074512_warren_abc123
project_id: alpha
written_at: 2026-06-26T07:45:12Z
history:
- version: 2
value: "Neutral — monitoring"
agent_id: qin
written_at: 2026-06-26T06:30:00Z
- version: 1
value: "Bearish — caution"
agent_id: warren
written_at: 2026-06-25T20:00:00ZEvery version. Every author. Full history. No "who changed this" mysteries.
Ambit emits structured violation events that Agent Illuminator captures natively as gap_detected events. One config line:
# agentilluminator.yaml
adapters:
ambit:
enabled: true
violations_dir: /path/to/workspace/.ambit/violationsIlluminator tells you what agents did. Ambit tells you whether they stayed within their declared scope while doing it. Together: behavioural observability from two independent angles.
Shared pipeline state without silent overwrites.
Multiple agents update a status flag — brief-status, task-complete, ready-for-review. Declare it shared. Conflicting writes within the window surface immediately instead of silently racing to the bottom.
Project memory that doesn't cross projects.
One agent, two client engagements. scope_by: project ensures context from engagement A doesn't surface in engagement B. Bleed events tell you when it would have.
Convergence verification.
After a multi-agent research pipeline, all agents should agree on the conclusion. Declare the conclusion key shared. If they don't agree, you find out before any downstream consumer reads the result.
Session-scoped working memory that actually expires.
Working notes for a session shouldn't persist into the next one. scope_by: session plus lifecycle rules means they don't. The session closes, the memory goes with it.
Audit trails for high-stakes workflows. Investment research. Compliance reporting. Client deliverables. Every write, every author, full version history, in a human-readable file that doesn't require a running database to read.
Catching bleed before it causes a bug.
Start with on_bleed: emit. Run for a week. Look at your violations. You will find at least one thing you didn't expect. Promote to block once you've cleaned them up.
Every tool in this table is useful. None of them do what Ambit does.
| mem0 / agentmemory / Letta | agent-recall / scope-recall | Agent Ambit | |
|---|---|---|---|
| Primary value | Remember more | Scoped retrieval | Enforce what belongs where |
| Retrieval | Semantic search, RAG | Namespaced semantic search | Not in scope — use a retrieval tool |
| Boundary enforcement | None | Namespace tags (advisory) | Policy per namespace, enforced |
| Contention detection | None | None | Built-in for shared |
| Bleed detection | None | None | Built-in for isolated |
| Violation events | None | None | Named, structured, attributable |
| Agent identity on writes | Partial | Partial | Required |
| Self-hosted | Some | Yes | Always |
The intended stack: a retrieval tool for what agents remember, Ambit for what they're allowed to. They don't compete.
workspace: /path/to/workspace
storage:
backend: file
data_dir: .ambit
retention_days: 90
on_expire: archive
namespaces:
market-state:
policy: shared
agents: [warren, qin, tony]
contention_window_sec: 300
on_contention: emit
project-alpha-memory:
policy: isolated
scope_by: agent
agents: [warren]
on_bleed: emit
pipeline-flags:
policy: shared
agents: [qin, warren, tony]
contention_window_sec: 60
on_contention: block
violations:
output_dir: .ambit/violations
illuminator_compatible: true- SQLite query CLI
- Violation webhooks (for external monitoring)
- MCP server (expose Ambit as an agent tool)
- Prometheus metrics exporter
- Agent Illuminator built-in adapter (not just compatible — native)
- Multi-workspace federation
MIT licensed. Best contributions: new scope_by modes, new violation handler actions, and adapters for runtimes you're actually running.
git clone https://github.com/terence-ma/agent-ambit
cd agent-ambit
pip install -e ".[dev]"
pytestSee CONTRIBUTING.md.
MIT. See LICENSE.
Part of a suite of agent infrastructure primitives. See also:
Agent Illuminator — workflow observability for autonomous agents
agentic-workflow-integrity — failure taxonomy and verification patterns