Starshard memory hub — Phase 0 reference implementation

A minimal, readable reference server for the memory substrate described in starshard-ai/architecture-v1.

Phase 0 ships four layers:

1. Memory hub — FastAPI + SQLite + JSON-RPC MCP bridge. Persistent, searchable memory for your agent(s). v0.3+ records carry an optional assumptions list and supersedes/superseded_by pointers.
2. Mirror consolidation — nightly scripts/mirror.py that reviews recent memories and writes proposal memories for your next session to review.
3. Assumption-layer conflict checker — scripts/assumption_checker.py runs every 12h, looks for logical conflicts between memory assumption sets (not just embedding similarity), surfaces proposals. Brian Williams ATMS-inspired; see SPEC-GAPS.md §12.
4. Weekly digest — scripts/digest.py SMTPs you a summary of what the system learned last week, so improvement is visible rather than invisible.

All three are Apache-2.0, written from the public architecture-v1 docs only (see SPEC-GAPS.md for interpretation decisions).

What you get when it's running

• Every Claude Code / Codex / MCP-capable agent session has persistent memory across machines and sessions.
• The templates/CLAUDE.md file tells your agent to use memory without you having to prompt it each turn — search_memories at session start, create_memory on every non-trivial decision.
• Mirror runs at 03:00 local, writes a single [Mirror] N proposals... memory you can review when you want.
• Sunday 22:00, you get an email titled [Starshard Weekly] ... — N memories with five crisp bullets of what the system learned.

Five-minute setup (local)

# 1. Generate a bearer token
python3 -c 'import secrets; print(secrets.token_urlsafe(32))' > .hub_token
cp .env.example .env
sed -i.bak "s/change-me.*/$(cat .hub_token)/" .env

# 2. Start the hub
docker compose --env-file .env up --build -d

# 3. Health check
curl -s http://localhost:8080/healthz
# -> {"ok":true,"version":"0.2.0"}

# 4. Wire your Claude Code — add to ~/.claude/mcp.json:
# {
#   "mcpServers": {
#     "starshard-hub": {
#       "type": "http",
#       "url": "http://localhost:8080/mcp",
#       "headers": {"Authorization": "Bearer <paste from .hub_token>"}
#     }
#   }
# }

# 5. Append templates/CLAUDE.md to ~/.claude/CLAUDE.md so the agent uses it.

Five-minute setup (AWS, your own box)

If you want the hub reachable from multiple devices:

export HUB_API_TOKEN=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')
echo "Save this token: $HUB_API_TOKEN"
bash scripts/deploy-aws.sh

Provisions a t4g.small in ap-northeast-1, installs Docker, runs the hub, prints public IP + MCP config snippet. Needs aws CLI configured (see INSTALL.md for the production-grade Cloudflare Tunnel variant — do that before trusting it with real data).

Self-improvement surfaces

Memory persistence alone is just storage. The value shows up when:

Mirror proposes consolidations overnight

# one-off test run
python -m scripts.mirror

# production: systemd timer (see deploy/README.md)
sudo cp deploy/mirror.systemd /etc/systemd/system/starshard-mirror.service
sudo cp deploy/mirror.timer   /etc/systemd/system/starshard-mirror.timer
sudo systemctl enable --now starshard-mirror.timer

Mirror reads the last 24h of memories, asks Claude to spot merge/supersede/add-tag opportunities, writes ONE proposal memory with up to five items. Your next Claude Code session (seeing awaits-user-approval tag) will surface them for your review.

Weekly digest keeps improvement visible

# one-off test run
python -m scripts.digest

# production: systemd timer, Sunday 22:00 local
sudo cp deploy/digest.systemd /etc/systemd/system/starshard-digest.service
sudo cp deploy/digest.timer   /etc/systemd/system/starshard-digest.timer
sudo systemctl enable --now starshard-digest.timer

Requires ANTHROPIC_API_KEY + SMTP_* + DIGEST_TO in .env.

REST surface

Method	Path	Purpose
POST	/memory	create_memory
GET	/memory/{id}	get_memory
PATCH	/memory/{id}	update_memory
GET	/memory	list_memories
POST	/memory/search	search_memories
POST	/mcp	MCP JSON-RPC
GET	/healthz	liveness (no auth)

All endpoints except /healthz require Authorization: Bearer <HUB_API_TOKEN>.

Tests

pip install -r requirements-dev.txt
export HUB_API_TOKEN=test-token
pytest -q

Project layout

app/                 hub server (see main.py for the route map)
scripts/             mirror + digest + deploy helpers
templates/           user-side CLAUDE.md to teach your agent
deploy/              systemd unit files + launchd notes
tests/               pytest suite
Dockerfile           python 3.12-slim + uvicorn
compose.yaml         one-command bringup + volume
INSTALL.md           Cloudflare Tunnel + Access walkthrough (production)
SPEC-GAPS.md         architecture doc gaps + interpretations made here

Companion repos

• starshard-ai/architecture-v1 — architecture / safety charter / quickstart / philosophy.

License

Apache-2.0. See LICENSE.