Shared agent context

Ambara helps every agent come prepared.

You record a decision or hand off work. Ambara turns that into project context, so the next agent, teammate, or session picks up where you left off.

One handoffthe human signal

Project contexthandled quietly

Connected agentsstart caught up

Input A person says "save this handoff"

1

PersonMarks work worth sharing

2

AmbaraFiles the useful context

3

Next sessionAgent starts already caught up

Result The developer using the next agent feels like it came prepared.

The problem

Where useful context lives today

People coordinate through chats, issues, local notes, meetings, and memory. Then they re-explain it all to each new agent session.

Chats and meetings

Decisions made in conversation, maybe written down, scattered across places agents never look.

Issues and PRs

Useful signals are in there somewhere, but good luck getting an agent to find the right ones at the right time.

Human memory

You remember why you did it that way. Tomorrow you won't. The next agent definitely won't.

AI agents make this worse. Config files give them project rules, but not what changed yesterday or what someone else is working on right now.

In practice

One handoff prepares every relevant future session.

You finish working on something and save a handoff. The next time you (or anyone) starts related work, the agent already knows what happened.

Tuesday evening → Wednesday morning

Auth migration

You, Tuesday → "I moved login to the new token endpoint but the refresh flow still uses the old one. Save this handoff."

You, Wednesday → "I'm picking up the auth work."

Agent: "Login uses the new token endpoint. The refresh flow still hits the old one. That's what's left."

You didn't re-explain anything. The agent read the handoff because it matched the code you're touching.

Usage

How developers interact with it

No new UI. You just talk to your agent like you already do.

"Save this as a project decision"

"We decided to standardize the terminology across all repos."

Recorded the terminology decision.

"Hand this off for the next session"

"Lab scripts are done, but the DNS issue on workstation is still open."

Saved the handoff.

Git-backedfull audit trail

Reviewabledecisions go through PR

Auto-expireshandoffs stay clean

Product promise

The experience is simple: the agent already knows.

Person

Just say what matters. "Save this handoff." "Record this decision."

Agent

Starts with project context and uses it when it matters.

Ambara

Handles the filing, review, search, and privacy stuff in the background.

No new UIworks through the agent

Reviewabledurable knowledge via PR

Temporary when neededhandoffs can expire

Cost of coordination

Config files handle instructions. Ambara handles what changed yesterday.

Project files give agents rules and preferences. But handoffs, decisions, and coordination signals change every day, and re-explaining them costs real time and tokens.

Ambara

$0.17

Agent + raw APIs

$2.02

Ask a colleague

$12.96

Manual lookup

$16.16

Standup (amortized)

$19.23

Solo developers

Without shared context, you typically spend a few extra turns re-explaining things each session. That can easily add up to $0.50-$2.00 in extra token cost plus several minutes of your time. Every session. Ambara replaces that with a compact context load and now reports the payload saved versus full eligible context.

Teams

Manual lookup = 10 minutes of a $200K/yr developer's time. Asking a colleague = 8 minutes across two people. Standup = 12 minutes amortized per coordination topic. Ambara keeps the savings visible with local value receipts, budget modes, and aggregate-only value ledgers.

The $0.17 is measured from real Claude Code sessions. The alternatives are modeled. Your numbers will vary, but the gap is real.

Privacy architecture

Privacy is baked into the architecture.

This isn't a policy page. Ambara literally has no collector for chats, editor activity, read receipts, or presence. It can't track what it was never built to capture.

IN

Intentional captureSaved notes and configured labels are the only publishing actions.

SRC

Allowlisted sourcesOnly configured repos, Jira projects, and provider sources are queried.

POL

Policy before writeSecrets and sensitive patterns are blocked or routed to review before git.

SC

Scoped retrievalRestricted, expired, superseded, and unrelated entries stay out of startup context and search.

NO

No surveillance data pathThe system cannot report data it never collects: read receipts, presence, chats, editor activity, or participation metrics.

Solo builders

One developer with four agents is already a team.

If you switch repos, restart sessions, or hand work between agents, you've got coordination state that should live outside the chat.

Future you

Save why a migration stalled and what to pick up next. No need to turn it into a whole document.

Parallel agents

One agent leaves a handoff so the next one doesn't rediscover the same blocker or repeat the same search.

Many repos

Context follows the work across repos instead of staying trapped in one checkout or session.

A team can be a company. It can also be you, your agents, and tomorrow.

Solo workflow

It keeps your work continuous when the chat ends.

You lose context too. The handoff might be from last night to this morning, from one repo to another, or from one agent to the next.

1

Start the dayThe agent loads what happened last session instead of asking you to explain it again.

2

Switch repos or agentsDecisions, blockers, and next steps follow the work wherever you go.

3

Leave a focused handoffFuture you gets the useful context without keeping every transcript forever.

For solo builders, the team is you, your agents, and the version of you that comes back tomorrow.

Architecture

Core library + transport adapters.

Pure core library with pluggable transport. Files for reads, CLI or MCP for writes. Works with any agent.

File adapterreads via context file

CLI commandsuniversal write path

MCP serverinteractive queries

Transport Adapters

File.ambara/context.md

CLIambara query / read

MCPinteractive tools

▼

Pure Core Library
schema · index · search · scoring · policy · planning

▼

Git I/Oclone · fetch · commit · push

ProvidersGitHub PRs · Jira

Engineering shape

The codebase separates logic from I/O.

Policy, orchestration, data sources, and git ops each live in their own module with clear boundaries.

core/All the rules: schema, validation, indexing, search ranking, signal classification, content policy, write planning. Zero I/O.

server.pyMCP tool handlers, sync lifecycle, and write orchestration.

cli.pyCLI commands: startup, query, read, record, propose. Same core, different transport.

git/Everything that touches the filesystem: clone, fetch, branch management, commits, and PR creation.

Key boundary: core/ must never import from git/ or providers/ or perform I/O. Enforced by AST guard in the test suite.

File adapter

Context loads at startup.

A SessionStart hook runs ambara startup, writes project context to a file, and the agent reads it as normal startup context.

hook firesSessionStartagent client starts

CLIambara startup--format md --output

write.ambara/context.mdproject context as markdown

agentreads the fileno tools, no permissions

Startup file

.ambara/context.md contains the current project context the agent should start with.

Agent contract

The project instruction tells the agent to read that file as part of its normal startup routine.

Universal read path

Any client that can read a file can use the same context, even without a dedicated integration.

Read path

Context comes from git, served through an in-memory index.

Git is the source of truth. The server keeps only local state it can rebuild from scratch: a repo cache and an in-memory search index.

clone/cacheensure_repo()cache path is remote hash

fetchfetch_all()main plus active refs

parseload_index_from_repo()markdown + YAML frontmatter

indexIndex + BM25rebuilt on sync

servefile / CLI / MCPany transport adapter

Key boundary: all indexing and ranking logic is pure. No network, no git calls, no filesystem access. I/O lives in separate modules.

Write safety

Content policy decides what can be published.

Before anything gets written to git, a policy gate checks the title, body, and metadata. It can block the write, require review, add a warning, or let it through.

intentrecord() / propose()CLI, MCP, or import

policyWritePolicy.evaluate()deterministic, offline

verdictblock / review / warn / allowrule IDs, not raw secrets

planplan_record()type, level, visibility

publishactive ref or PRonly after policy passes

Policy result	What it catches	What happens
`block`	Private keys, API keys, live keys, URI credentials, secret assignments	The write stops. The user gets a safe message without the secret echoed back.
`require_review`	Email, phone numbers, SSNs, confidentiality terms, personnel judgments	The content is routed to review instead of becoming shared guidance immediately.
`allow_with_warning`	Risky phrasing, weak prompt-injection text, profanity	The write can continue, but it carries a warning label for reviewers.
`allow`	No policy findings	The normal write plan continues: temporary handoff, lightweight PR, or review PR.

The same policy engine protects CLI writes, MCP writes, and import dry-runs. It stores policy outcomes and rule IDs, not raw rejected secrets.

Governance model

Metadata tells agents how much to trust each entry.

An entry isn't just a markdown file. The frontmatter tells the agent what kind of knowledge it is, how reviewed it is, whether it expires, and whether it's safe to show.

type: active
level: L0
status: active
projects: [auth-migration]
expires_at: 2026-06-01T18:00:00Z
visibility: internal

TYP

What is this?Active handoff, project fact, workflow, decision, or principle.

LVL

How reviewed is it?L0 can move immediately. L1 gets quick review. L2/L3 need deliberate review.

TTL

How long should it matter?Status and expiration remove stale, superseded, and unrelated work from startup context.

SC

Where should it appear?Project, tags, visibility, and sensitivity keep context relevant and appropriately quiet.

Result: agents use a handoff as short-term context, but treat reviewed workflows, decisions, and principles as durable team guidance.

Cross-client

Works on Claude Code, Gemini CLI, any agent.

Every agent can read a file. Same context file, same CLI commands, works across clients.

Claude Code

SessionStart hook writes .ambara/context.md. CLAUDE.md tells the agent to read it.

Tested & validated

Gemini CLI

Same hook, same file. GEMINI.md gets the startup contract. Works through the file adapter.

Supported, not yet integration-tested

Any future client

If it can read a file and run a shell command, it can use Ambara. No SDK, no plugin, no MCP required.

By design

The hybrid model: files for startup context, MCP for interactive queries when available, CLI as the universal fallback.

Configured signals

Labels are opt-in publishing, across GitHub, Jira, and future systems.

Today, Ambara reads labeled GitHub PRs and Jira issues from configured sources. A future provider must follow the same rule: configured source, configured label or tag, normalized summary.

allowlistRepos + projectsconfigured sources only

providersGitHub PRs + Jira issuesadapters, not crawlers

label gateConfigured label/tagunlabeled work ignored

normalizeCoordinationSignalsummary, status, links

classifyclassify_signals()guidance for agents

Provider neutral boundary: no unlabeled work items, PR comments, Jira comments, chats, editor activity, read activity, or broad mining enter this path.

Get started

Try it in two minutes.

Install, onboard your project, and restart your agent. The next session starts with shared context.

Python 3.12+requirement

Any git hostGitHub, GitLab, etc.

Any MCP clientor just file reads

# Install
pip install ambara

# Set up your project
cd your-project
ambara onboard

# Ambara creates:
#   - Knowledge repo scaffold
#   - CLAUDE.md startup contract
#   - MCP server configuration
#   - Tool permissions

# Verify everything works
ambara doctor --team --check-startup

# Restart your agent. It starts
# with shared context automatically