microsoft/amplifier-context-intelligence

microsoft/amplifier-context-intelligence

Description: Context Intelligence services for the Amplifier project

Language: Python

License: MIT

Stars: 2

Forks: 1

Open issues: 1

Created: 2026-03-25T13:11:30Z

Pushed: 2026-06-14T00:23:02Z

Default branch: main

Fork: no

Archived: no

README:

Context Intelligence Server

An event-driven telemetry platform for Amplifier sessions. Captures session events as structured data and builds a property graph in Neo4j.

How It Works

Amplifier CLI sessions
|
| hook-context-intelligence (thin forwarder)
| POST /events {event, workspace, data}
v
+------------------------------------------+ +----------------------+
| Ingestion Server (:8000) | bolt | Neo4j |
| - Event processing pipeline |------->| :7687 bolt/driver |
| - Blob storage (large payloads to disk) | | :7474 browser UI |
| - Dashboard + API docs | | Property graph |
| - Cypher proxy | | 5 node / 8 edge types|
+------------------------------------------+ +----------------------+

---

Running with Docker Compose

Prerequisites

• Docker and Docker Compose

1. Clone the repository

git clone https://github.com/microsoft/amplifier-context-intelligence.git
cd amplifier-context-intelligence

2. Start the stack (first run)

On first run, use the start.sh script to generate credentials and start the stack:

./start.sh

This generates credentials (credentials.yaml + neo4j-auth.env), then calls docker compose up -d to start the services.

To retrieve your API key after the first run:

grep api_key ~/amplifier-context-intelligence-server-data-store/credentials.yaml

2a. Restart the stack (subsequent runs)

On subsequent restarts, the credentials already exist, so you can use docker compose directly:

docker compose up -d

Services

The stack runs 2 services:

| Service | Port | Description | |---------|------|-------------| | Ingestion server | localhost:8000 | Event processing, dashboard, API | | Neo4j | browser localhost:7474 · bolt :7687 | Property graph (auth enabled) |

All services are configured with restart: unless-stopped — they automatically restart on crash or Docker daemon restart. They only stay down if you explicitly stop them with docker compose stop or docker compose down.

3. Access the dashboard

Open http://localhost:8000 — this is the single navigation hub for the system.

| Route | Content | |-------|---------| | / | Landing page with navigation cards | | /dashboard | Live session monitoring, event history, log stream | | /docs | Swagger API documentation |

The home page and dashboard both show:

• Neo4j status (Connected / Disconnected) polled every few seconds
• Neo4j Bolt URL — the exact value of neo4j_url from server-config.yaml
• Neo4j Browser URL — the exact value of neo4j_browser_url from server-config.yaml, as a clickable link

Both URLs are displayed verbatim from the configuration. If Neo4j is on a remote host, the displayed values reflect that remote address — not localhost.

When api_key is configured, the dashboard shows an API key prompt on first visit — enter the key from credentials.yaml.

---

Running with Docker (single container)

Build the image then run with explicit port and volume mounts:

docker build -t context-intelligence-server .
docker run -d \
--name context-intelligence-server \
-p 8000:8000 \
-v "$HOME/amplifier-context-intelligence-server-data-store:/data" \
-e AMPLIFIER_CONTEXT_INTELLIGENCE_SERVER_API_KEY= \
-e AMPLIFIER_CONTEXT_INTELLIGENCE_SERVER_NEO4J_URL=bolt://your-neo4j:7687 \
-e AMPLIFIER_CONTEXT_INTELLIGENCE_SERVER_NEO4J_PASSWORD= \
context-intelligence-server

Retrieve the generated API key after first run:

docker exec context-intelligence-server grep api_key /data/credentials.yaml

---

First-Run Setup (Standalone)

Before starting the server for the first time outside Docker, run the init command to generate credentials:

context-intelligence-server init \
--neo4j-url bolt://localhost:7687 \
--neo4j-browser-url http://localhost:7474 \
--neo4j-user neo4j

You will be prompted for the Neo4j password. The command writes server-config.yaml with all required fields including a generated api_key. The generated API key is printed to stdout — copy it to your bundle config as context_intelligence_api_key.

--neo4j-url is the bolt driver URL (used for all graph operations). --neo4j-browser-url is the Neo4j Browser HTTP URL (displayed as a clickable link in the web UI). If Neo4j is on a remote host, use that host in both values.

---

Running Without Docker

Run the server as a plain Python process against any Neo4j instance — useful for local development, custom deployments, or environments where Docker is unavailable.

Prerequisites

• Python 3.11+
• uv
• A running Neo4j instance (see below)

1. Install dependencies

git clone https://github.com/microsoft/amplifier-context-intelligence.git
cd amplifier-context-intelligence
uv sync

2. Start a Neo4j instance

Option A — Docker (easiest):

docker run -d --name neo4j-ci \
-p 7474:7474 -p 7687:7687 \
-e NEO4J_AUTH=none \
neo4j:5.26.22-community

Option B — Neo4j Desktop / existing instance:

Use any Neo4j 5.x instance. Note the bolt URL, username, and password — you will need them in the next step.

3. Configure the server

The server accepts configuration from a YAML file, environment variables, or both. Environment variables always take precedence over the YAML file.

Option A — YAML configuration file (recommended)

Copy the example file and edit it:

cp server-config.example.yaml server-config.yaml

Edit server-config.yaml:

# Neo4j connection
neo4j_url: neo4j://localhost:7687 # bolt/driver URL (used for graph operations)
neo4j_browser_url: http://localhost:7474 # browser UI URL (clickable link in web UI)
neo4j_user: neo4j
neo4j_password: "" # empty string for NEO4J_AUTH=none instances

# Storage — directories are created automatically
blob_path: /home/you/.local/share/ci-server/blobs
log_path: /home/you/.local/share/ci-server/logs/server.jsonl

# Server bind address — 0.0.0.0 accepts connections from all interfaces,
# including Docker/Incus container...