microsoft/amplifier-bundle-context-intelligence

microsoft/amplifier-bundle-context-intelligence

Description: Context Intelligence bundle for the Amplifier project

Language: Python

License: MIT

Stars: 1

Forks: 1

Open issues: 5

Created: 2026-03-25T13:10:04Z

Pushed: 2026-06-10T18:39:36Z

Default branch: main

Fork: no

Archived: no

README:

amplifier-bundle-context-intelligence

An Amplifier bundle that captures session events as structured data for analysis and querying.

The bundle writes every session event to a local JSONL log and — when configured with a server URL — forwards events to the Context Intelligence Server for graph storage and blob management.

---

What it does

| Always active | When context_intelligence_server_url is set | |---------------|-----------------------------------------------| | Writes events.jsonl + metadata.json per session, both tagged with workspace | POSTs every event to the CI server | | | Enables graph-powered Cypher queries via graph_query tool | | | Enables blob_read tool for resolving ci-blob:// URIs |

Two agents are included for querying session data:

• `graph-analyst` — primary entry point. Queries the context-intelligence property graph using Cypher, resolves ci-blob:// URIs, and automatically delegates to session-navigator when the graph server is unreachable or returns 0 sessions.
• `session-navigator` — local fallback agent. Navigates session data via flat JSONL files using safe bash/jq/grep extraction patterns when the server is unavailable. Invoked only by graph-analyst via the delegation chain — external callers should use graph-analyst as the entry point.

A `/context-intelligence` mode is also included for building new context intelligence-aware tooling. Activate it to enter a design workspace where you can investigate session data, explore the graph model, and produce reusable Amplifier components (skills, agents, context files, recipes, CLIs) for your project.

---

Understanding workspace

Workspace is the primary isolation boundary for event data. It is written into every local file and every server POST — sessions in different workspaces are completely independent whether queried locally or via the graph. Typical uses: separate projects (my-api, frontend), separate environments (dev, staging, prod), or separate teams on a shared server.

How workspace appears in data

workspace is a top-level field in all three places data is written:

`events.jsonl` — every line:

{"event":"session:start","workspace":"my-project","timestamp":"2026-01-15T10:23:44.123Z","data":{"session_id":"abc-123","working_dir":"/home/user/myapp",...}}

`metadata.json` — session-level record:

{"format":"context-intelligence","version":"1.0.0","session_id":"abc-123","workspace":"my-project","parent_id":"","started_at":"2026-01-15T10:23:44.123Z","last_event_at":"2026-01-15T10:23:59.789Z","status":"completed","ended_at":"2026-01-15T10:24:01.456Z","working_dir":"/home/user/myapp"}

Server POST (POST /events) — forwarded to the CI server:

{"event":"session:start","workspace":"my-project","idempotency_key":"aci-event-v1:","data":{...}}

Resolution priority

The hook resolves workspace using the same config → coordinator → default pattern as all other properties:

| Priority | Source | Notes | |----------|--------|-------| | 1 (highest) | config["workspace"] | From settings.yaml or env var — see [Configuration reference](#configuration-reference) | | 2 | coordinator.config["workspace"] | Set programmatically before the session starts — see [Embedding](#embedding-in-an-amplifier-application) | | 3 (lowest) | project_slug derived from working directory | Automatic — /home/user/my-api becomes -home-user-my-api |

---

Quick Start

1. Install

Add to an existing app (recommended) — layers the behavior on top of your active bundle without pulling in foundation as a dependency:

amplifier bundle add git+https://github.com/microsoft/amplifier-bundle-context-intelligence@main#subdirectory=behaviors/context-intelligence.yaml --app

Standalone — creates a dedicated session configuration using the full root bundle (includes foundation):

amplifier bundle add git+https://github.com/microsoft/amplifier-bundle-context-intelligence@main
amplifier bundle use context-intelligence

Every Amplifier session will now write events to local JSONL files automatically — no server required.

2. (Optional) Enable server forwarding

To push events to the Context Intelligence Server for graph storage and querying, you need a running server instance and its API key. See the server repository for setup instructions.

Once the server is running, add the URL and API key to ~/.amplifier/keys.env — the same file that holds LLM provider keys, loaded automatically by Amplifier on startup and never committed to version control:

# ~/.amplifier/keys.env
AMPLIFIER_CONTEXT_INTELLIGENCE_SERVER_URL=http://localhost:8000
AMPLIFIER_CONTEXT_INTELLIGENCE_API_KEY=

The behavior YAML already contains ${AMPLIFIER_CONTEXT_INTELLIGENCE_SERVER_URL:} and ${AMPLIFIER_CONTEXT_INTELLIGENCE_API_KEY:} placeholders that resolve these automatically — no settings.yaml entry is required.

> Never write a literal API key into `settings.yaml`. That file is version-controllable configuration; a secret written there is one accidental commit away from exposure.

3. Verify

After running a session:

ls ~/.amplifier/projects//sessions/*/context-intelligence/
# events.jsonl metadata.json

head -1 ~/.amplifier/projects//sessions/*/context-intelligence/events.jsonl | jq .workspace
cat ~/.amplifier/projects//sessions/*/context-intelligence/metadata.json | jq .workspace

If the server is configured, open http://localhost:8000/dashboard — your session will appear once authenticated.

---

Exploration guide

If you're wondering what's worth trying after getting set up, [docs/context-intelligence-exploration-guide.md](docs/context-intelligence-exploration-guide.md) is a curated list of things to explore — verifying the connection, testing session capture, querying the graph, and more. Not a formal test plan; more…