Ambient

Autonomous agent fleet for ambient computing. Agents run 24/7 in Docker, store knowledge in a Memgraph graph database, consolidate memories overnight, and surface a morning briefing for you to review on your phone.

Prerequisites

• Python 3.12+
• Docker & Docker Compose
• A Google AI Studio API key (Gemini)

Setup

# 1. Clone the repo
git clone https://github.com/javiergarci/ambient.git
cd ambient

# 2. Create your .env file
cp .env.example .env
# Edit .env and add your GOOGLE_API_KEY

# 3. Run bootstrap (starts Memgraph, creates venv, installs deps, seeds schema)
./scripts/bootstrap.sh

# 4. Activate the virtual environment
source .venv/bin/activate

Usage

Interactive mode

Talk to the orchestrator agent directly:

python -m ambient.main

Javier> Remember that my supplier is Acme Logistics in San Jose, Costa Rica
Javier> What do I know about Acme?
Javier> Draft an email to the supplier about the delayed shipment
Javier> quit

Single-shot mode

python -m ambient.main "What pending approvals do I have?"

Run everything in Docker

docker compose up

This starts:

Service	Port	Description
Memgraph	7687	Knowledge graph (Bolt protocol)
Memgraph Lab	3000	Visual graph explorer
Briefing API	8000	Morning briefing + approvals REST API
Orchestrator	—	Root agent (interactive)

Briefing API

The API serves morning briefings and approval workflows for the PWA:

# Get today's briefing
curl http://localhost:8000/briefing

# List pending approvals
curl http://localhost:8000/approvals

# Approve an item
curl -X POST http://localhost:8000/approvals/<id> \
  -H "Content-Type: application/json" \
  -d '{"action": "approve", "note": "Looks good"}'

# View knowledge graph stats
curl http://localhost:8000/graph/stats

# Manually trigger overnight consolidation
curl -X POST http://localhost:8000/consolidation/trigger

# Manually trigger morning briefing generation
curl -X POST http://localhost:8000/briefing/trigger

Explore the knowledge graph

Open http://localhost:3000 (Memgraph Lab) and run:

-- See everything
MATCH (n) RETURN n;

-- See all entities and their relationships
MATCH (a:Entity)-[r]->(b:Entity) RETURN a, r, b;

-- See recent episodes
MATCH (e:Episode) RETURN e ORDER BY e.timestamp DESC LIMIT 20;

-- See pending approvals
MATCH (a:Approval {status: 'pending'}) RETURN a;

How it works

Agents

The system uses Google ADK (Python) with Gemini. Agents are organized in a hierarchy:

• Orchestrator — routes tasks to specialists
  • Inbox Agent — email drafting and triage
  • Ops Agent — operational tasks and monitoring

Every agent has access to knowledge graph tools (remember, recall, store_entity, relate_entities) and approval tools (request_approval).

Knowledge Graph (Memgraph)

All knowledge is stored as a graph:

• Entities — open-schema nodes (people, companies, products, concepts)
• Episodes — timestamped observations, decisions, and events
• Relationships — typed edges between entities (dynamic, any type)

Sleep Cycles

Overnight (default 3 AM), the consolidation engine:

1. Runs PageRank on entities to score importance
2. Runs community detection to cluster related entities
3. Applies memory decay — old, unimportant episodes fade out
4. Prunes episodes below the decay threshold

Morning Briefing

At wake time (default 7 AM), the system generates a briefing with:

• Pending approval items from the agent fleet
• Highlights from recent high-importance episodes
• Graph statistics

Adding a new agent

1. Create src/ambient/agents/your_agent.py using the create_agent() factory
2. Add it as a sub-agent in orchestrator.py
3. Optionally add agent-specific tools in src/ambient/tools/
4. Add a Docker service in docker-compose.yml if it needs its own container

Environment variables

Variable	Default	Description
GOOGLE_API_KEY	—	Gemini API key (required)
MEMGRAPH_HOST	localhost	Memgraph hostname
MEMGRAPH_PORT	7687	Memgraph Bolt port
BRIEFING_API_PORT	8000	Briefing API port
AGENT_OWNER_NAME	Javier	Your name (used in prompts)
SLEEP_CYCLE_HOUR	3	Hour to run consolidation (24h)
WAKE_CYCLE_HOUR	7	Hour to generate briefing (24h)
TIMEZONE	America/Costa_Rica	Timezone for scheduling

Tests

# Requires Memgraph running
source .venv/bin/activate
pytest