HAM - Shared Memory for Collaborating Agents

HAM is a PostgreSQL-backed memory service for agents working across sessions, repositories, projects, and tools. Text is encoded locally with deterministic Clifford/geometric encoders, so the core service does not require an embedding API or GPU.

The production model is deliberately simple:

Codex / Claude / Cursor / other MCP clients
  -> local stdio MCP bridge
  -> authenticated HAM HTTP API
  -> PostgreSQL + pgvector (canonical memory and provenance)

Each deployment can contain many tenants. Within a tenant, agents share memory through explicit scopes while preserving the originating agent, project, repo, task, thread, state, and version of every item.

Agent Workflows

The MCP bridge exposes:

• ham_remember - store a scoped observation, fact, decision, preference, or note.
• ham_recall - semantic and lexical search in the active collaboration context.
• ham_recent - see recent work without having to invent a search query.
• ham_changes - catch up from an ISO-8601 cursor.
• ham_handoff - publish completed work, next steps, blockers, and touched files.
• ham_get - fetch a complete memory with provenance and version.
• ham_supersede - replace stale knowledge with optimistic concurrency.
• ham_retract - mark incorrect knowledge inactive without deleting its history.
• ham_reflect and ham_context - close and reopen working sessions.

Scopes are arbitrary lower-case labels such as shared, project:ham, repo:monumentalsystems/ham, or task:deploy. MCP clients should use the same tenant ID and distinct agent IDs.

Quick Start

Create .env from .env.example, generate strong values for HAM_DB_PASS and HAM_API_KEY, then run:

docker compose up --build -d
curl http://127.0.0.1:8042/health/ready

The Compose stack starts a private pgvector/pgvector:pg16 database and binds the API to 127.0.0.1:8042. The entrypoint creates the required vector, pg_trgm, and intarray extensions and applies all idempotent migrations in a serialized transaction.

To test an authenticated request:

curl -H "Authorization: Bearer $HAM_API_KEY" \
  -H "X-GB-User-ID: shared-team" \
  http://127.0.0.1:8042/stats

MCP Configuration

The stdio process is a thin bridge to the shared API. In normal shared-service mode it requires HAM_API_URL and does not need database credentials.

{
  "mcpServers": {
    "ham": {
      "command": "python",
      "args": ["-m", "pg_ham.mcp_server"],
      "cwd": "/path/to/ham",
      "env": {
        "HAM_API_URL": "http://127.0.0.1:8042",
        "HAM_API_KEY": "replace-me",
        "HAM_MCP_USER_ID": "shared-team",
        "HAM_AGENT_ID": "codex",
        "HAM_SCOPES": "shared,project:ham,repo:monumentalsystems/ham",
        "HAM_PROJECT": "ham",
        "HAM_REPO": "MonumentalSystems/ham"
      }
    }
  }
}

Give each agent a distinct key in HAM_AGENT_KEYS_JSON, and configure that key as its HAM_API_KEY. The server binds the key to its tenant and agent identity; client-supplied identity headers cannot override it. Set HAM_TASK and HAM_THREAD when the host can provide them. Local clients can reach a private remote deployment through an SSH tunnel without exposing HAM or PostgreSQL.

Legacy direct-PostgreSQL MCP mode is disabled by default. Local research setups can opt in with HAM_MCP_DIRECT_DB_ENABLED=true and the HAM_DB_* variables, but this grants the MCP process database credentials and is not recommended for shared or multi-user deployments.

Collaboration Contract

Per-agent keys are the normal tenant boundary. HAM_API_KEY is the separate administrator key and may select a tenant with X-GB-User-ID; it is required for hard delete, reset, graph rebuild, enrichment, and research endpoints. Unsigned identity headers are accepted only when HAM_TRUST_IDENTITY_HEADER=true behind an authenticated proxy. HAM_SINGLE_USER_ID is for local development.

Every collaborative memory stores standardized JSON metadata:

Field	Purpose
agent_id	Agent that produced the memory.
scopes	Shared contexts in which the memory is discoverable.
project, repo, task, thread	Work provenance and filtering.
type	observation, fact, decision, handoff, and similar kinds.
status, importance	Agent-facing workflow state and priority.
visibility	shared or organizationally private to the originating agent.
idempotency_key	Stable retry key that prevents duplicate writes.

Rows also carry state, version, updated_at, and supersedes_id. Search returns active memories; the change feed includes superseded and retracted items so agents can update their local understanding.

API Surface

Endpoint	Method	Purpose
/health/live, /health/ready	GET	Container and dependency health.
/ingest, /ingest/batch	POST	Consistent complete ingestion.
/search	POST	Scoped semantic, spectral, and lexical search.
/memories/recent	POST	Recent active context.
/changes	POST	Cursor-based catch-up feed.
/memories/{id}	GET	Full memory and provenance.
/memories/{id}/supersede	POST	Immutable replacement.
/memories/{id}/retract	POST	Auditable retraction.
/stats, /consolidate	GET / POST	Tenant memory lifecycle.

Legacy and research retrieval endpoints remain available. PostgreSQL is the production authority. QKPS and legacy pickle-backed fields are disabled by default (HAM_QKPS_ENABLED=false, HAM_LEGACY_FIELD_ENABLED=false) because they are process-local accelerators and should not define shared consistency.

Security

• Keep PostgreSQL private and give agents only HAM_API_URL and HAM_API_KEY.
• Prefer a private network or SSH tunnel; do not publish HAM directly to browsers.
• Leave CORS empty unless a trusted browser application genuinely needs it.
• Use per-agent credentials for every MCP client. Keep the administrator key out of agent environments; it can hard-delete or reset tenant data.
• Application authorization is enforced before queries. PostgreSQL row-level security remains useful future defense in depth for mutually untrusted operators.
• Back up PostgreSQL off-host and test restoration.

Development

pip install -r requirements.txt -r requirements-dev.txt
python -m py_compile pg_ham/server.py pg_ham/mcp_server.py scripts/e2e_collaboration.py
pytest -q
ruff check pg_ham/server.py pg_ham/mcp_server.py scripts tests

Training and benchmark scripts remain research tooling. Generated datasets, checkpoints, embeddings, field snapshots, and logs must stay out of git.

License

HAM is available under the Apache License 2.0.