Getting started

Goal: a running deployment, one ingested document, and a first honest query — in one sitting.

Managed-cloud humans can run remember login --token-host <url> instead of pasting a long-lived secret; self-host Compose still uses the local API URL below.

Choose a path

This page uses Compose. Full operator detail: Self-host deployment.

Prerequisites

• Docker Engine with Compose v2
• An OpenRouter API key (or equivalent model seats) for extraction and embeddings
• ~10 minutes for first boot + smoke ingest

1. Start the stack

git clone https://github.com/writeitai/remember-stack.git
cd remember-stack
cp .env.example .env
# Set OpenRouter (or configured provider) credentials in .env
docker compose up --build --detach --wait

The Compose file can also pull the public ghcr.io/writeitai/remember-stack:0.13.0 image. Use --build when you want to run local source; use --no-build --pull always when you want the released image.

Health:

curl --fail http://localhost:8000/healthz
curl --fail http://localhost:8000/operations

You should see the four assured operations: resolve_entity, testimony_context, fact_context, and answer_context.

2. Ingest a document

The fresh self-host profile ships a Markdown conversion route. Other MIME types need additional conversion routes registered on the deployment (the engine design supports them; the smoke profile does not auto-route PDF/audio/video).

printf '# Hello\n\nAlice is the CFO of Acme as of 2024.\n' > /tmp/remember-smoke.md
curl --fail \
  -H 'content-type: application/octet-stream' \
  --data-binary @/tmp/remember-smoke.md \
  'http://localhost:8000/ingest?filename=remember-smoke.md&mime=text%2Fmarkdown'

The response names deployment_id, doc_id, and version_id. Save the version id for readiness.

What just happened (short form):

1. Bytes stored immutably (E0)
2. Markdown + structure derived
3. Chunks packed deterministically (E1)
4. Claims extracted and grounded (E2)
5. Entities resolved; facts adjudicated (E3)
6. Search indexes updated (P1)

Detail: Ingestion.

3. Wait until the version is ready

Prefer the machine-verifiable readiness endpoint over shelling into Postgres:

# replace VERSION_ID with the ingest response version_id
curl --fail -X POST http://localhost:8000/readiness \
  -H 'content-type: application/json' \
  -d '{"version_ids":["VERSION_ID"],"require":{"pipeline":true,"p1":true,"live_graph":true,"p3":false}}'

All four capability keys are mandatory. Ordinary recall requires the pipeline, P1, and live graph; require P3 only when the caller needs the published corpus filesystem.

Human fallback if you need stage detail:

docker compose exec postgres psql -U rememberstack -d rememberstack -c \
  "SELECT stage, status FROM processing_state ORDER BY enqueued_at"

4. Publish P3 (when you need the corpus filesystem)

The graph is already live in PostgreSQL. P3 remains a whole-corpus build:

docker compose --profile operations run --rm projections

5. First retrieval — four assured ops

Argument names match the operation registry and API reference.

Resolve an entity

curl --fail -X POST http://localhost:8000/operations/resolve_entity \
  -H 'content-type: application/json' \
  -d '{"name":"Alice"}'

Query-time resolve is exact-name (T0) in the current surface: ambiguity among exact aliases is returned as ranked candidates, never guessed away. Fuzzy/phonetic/embedding tiers run on the write-time resolution cascade, not this hot path.

Evidence context for a question

curl --fail -X POST http://localhost:8000/operations/testimony_context \
  -H 'content-type: application/json' \
  -d '{"query":"Who is the CFO of Acme?"}'

Returns evidence grain (claims + chunks) — testimony, not the adjudicated verdict alone.

Current-fact context

curl --fail -X POST http://localhost:8000/operations/fact_context \
  -H 'content-type: application/json' \
  -d '{"query":"Who is the CFO of Acme?","time":{"mode":"current"}}'

Returns fact grain with live testimony under a hard evidence budget. Use at, overlap, or history time mode when the question is about past world-valid state; omit entity_ids for deployment-wide retrieval or pass confirmed IDs to start the default one-hop entity-neighborhood recipe. Current/at calls walk every relation by default—including other:*—then search relation and observation text inside the capped ID union. Optional predicate narrows to that exact stored relation name; hops accepts 1–2.

Both authority views

curl --fail -X POST http://localhost:8000/operations/answer_context \
  -H 'content-type: application/json' \
  -d '{"query":"Who is the CFO of Acme?"}'

Returns ContextBundle/v1 with the complete evidence-grain response under testimony and the complete fact-grain response under facts. The two are not flattened or re-ranked together.

What to read on the envelope first

Single-grain Envelope answers are flat:

{
  "grain": "fact",
  "temporal_scope": {
    "mode": "current",
    "evaluated_at": "…",
    "believed_at": "…",
    "identity_regime": "current"
  },
  "facts": [{ "fact_id": "…", "kind": "relation", "label": "…", "evidence_count": 1, "support": "current" }],
  "fact_evidence": [{ "fact_kind": "relation", "fact_id": "…", "claim_id": "…", "stance": "supports" }],
  "evidence": [{ "claim_id": "…", "claim_text": "…", "is_current_testimony": true }],
  "freshness": { "pg_live_ts": "…", "p1_written_inline": true },
  "dropped_by_hydration": 0,
  "negative": null
}

Agent checklist:

1. Read grain
2. If negative is set — branch on kind (unknown_entity | known_empty | boundary)
3. Prefer facts + fact_evidence for present-tense belief
4. Drill evidence / sources before irreversible action
5. For ContextBundle/v1, inspect testimony and facts as separate complete envelopes

Full contract: Response envelope.

6. Open query (optional, powerful)

curl --fail http://localhost:8000/query/space

Example — current facts only:

curl --fail -X POST http://localhost:8000/query/sql \
  -H 'content-type: application/json' \
  -d '{"sql":"SELECT fact_kind, fact_id, predicate FROM facts_current LIMIT 20"}'

Wrong pattern: filtering claims_live validity windows to answer “what is true now.” Claim windows are asserted testimony, not system belief. Start from facts_current. See Open query space.

7. Agent path

Surfaces available immediately without mounts: API / CLI / MCP (same four assured ops + open query).

Mounts (P3 corpus tree, artifacts, raw, Plane K checkout) are published through the library mount APIs for a deployment — not a separate Compose service in the smoke profile. When your harness can mount:

1. Obtain PublishedMounts from the self-host mount publisher for this deployment.
2. Render/publish the consumption SKILL.md via ConsumptionSkillSurface.
3. Prefer filesystem for navigate/read/grep; use MCP/API for search/graph/time-travel.

Details: Mounts and skill.

Install without Compose

Client (remote deployment):

pip install rememberstack
# or: uv add rememberstack

Named install surfaces (see package extras):

pip install 'rememberstack[server]'
pip install 'rememberstack[connectors-watched-directory]'
pip install 'rememberstack[k]'

Next

• Concepts — claim vs fact vs grain
• Ingestion — full write path
• Retrieval — full read path
• Deployment — Compose lifecycle and projections
• Configuration — env, model seats, budgets
• Troubleshooting — stuck work and empty retrieval