​

Memory System

​

Overview

​

When to use it

• An agent has long-running user-specific preferences. Dark-mode preference, preferred PR style, favourite framework, “use PostgreSQL 16 for new DBs” — anything the user shouldn’t have to repeat on every new chat. Persist to AGENT.md once, retrieve forever.
• A crew needs a single source of truth for conventions and decisions. Architecture decisions, deployment rules, security policies, “we always use Tailwind, never inline styles” — the lead curates CREW.md and every member-agent reads it. Beats stuffing the same instructions into each agent’s system prompt by hand.
• An agent is accumulating project context. A code-review agent reading the same repo every day shouldn’t relearn the module layout each session. Daily logs (daily/2026-05-14.md) capture session observations; FTS5 search surfaces them when the same module comes up again.
• A single-agent crew that should specialise over time. Without crew peers the budget is 100% agent-tier — the agent essentially gets a persistent notebook. Useful for “my personal research assistant” or “the on-call bot that remembers last week’s incidents.”
• You’re domain-mining knowledge with topics/. When the crew has bounded subject areas (deployment, security, billing), populate topics/<name>.md files. Hybrid search ranks them above the daily noise on relevant queries.

​

Key concepts

​

Usage

crewship agent create --name "Researcher" --memory
# or for an existing agent:
crewship agent update researcher --memory

# Append a long-term fact to AGENT.md
echo "## Preference\nUser likes terse PR descriptions." >> ~/.memory/AGENT.md

# Drop a session-specific note in today's daily log
echo "- Investigated auth/middleware refactor; chose option B." \
  >> ~/.memory/daily/$(date -I).md

curl -sX POST localhost:9119/memory/search \
  -d '{"query": "PostgreSQL migration strategy", "scope": "both", "limit": 5}'

​

Examples

​

A research-assistant agent that remembers user preferences

echo "## User preferences\n- Prefers terse commit subjects (≤70 chars)\n- Wants CHANGELOG entries in same PR, not follow-up" \
  >> ~/.memory/AGENT.md

​

A crew lead recording an architectural decision once

echo "## Decision (2026-05-14): PostgreSQL 16 for all new DBs\n- driver: pgx v5\n- migrations: internal/database/migrate.go\n- ADR-007 in repo for full context" \
  >> /crew/shared/.memory/CREW.md

​

Bounded subject expertise via topics/

/crew/shared/.memory/topics/deployment.md   # 4kB on Kubernetes + Helm conventions
/crew/shared/.memory/topics/billing.md      # 2kB on Stripe webhook handling
/crew/shared/.memory/topics/security.md     # 6kB on Keeper credential policies

​

Memory Tiers

CREW SHARED MEMORY (Lead-owned)
  Container: /crew/shared/.memory/
  Who writes: Lead               Who reads: all agents in crew
  Budget: max 40% of system prompt
  FTS5: Lead sidecar owns index (single writer, zero contention)

AGENT MEMORY (per-agent, private)
  Container: /crew/agents/{slug}/.memory/
  Who writes: the agent itself   Who reads: only that agent
  Budget: remainder (60-100%)

SESSION MEMORY (ephemeral)
  Lives in the LLM context window, not persisted

​

Enabling Memory

crewship agent create --name "My Agent" --memory

​

File Structure

​

Agent Memory

~/.memory/
  AGENT.md              # Long-term curated facts (evergreen)
  daily/
    2026-04-14.md       # Today's session notes
    2026-04-13.md       # Yesterday's notes
  index.sqlite          # FTS5 search index (sidecar manages)

​

Crew Shared Memory

/crew/shared/.memory/
  CREW.md               # Crew conventions, decisions, policies
  daily/
    2026-04-14.md       # Crew daily log
  topics/
    deployment.md       # Domain-specific knowledge
    security.md
  index.sqlite          # FTS5 index (Lead sidecar owns)

​

How It Works at Runtime

​

1. Writing Memory

# Agent writes to its personal memory
echo "## New Fact\nUser prefers dark mode" >> ~/.memory/AGENT.md

# Lead writes to crew shared memory
echo "## Decision\nUse PostgreSQL 16 for all DBs" >> /crew/shared/.memory/CREW.md

• A successful memory.write is fsync’d and atomically renamed into place before it returns — a write the tool reports as done is on stable storage, never merely in the page cache.
• If the persist cannot complete, the tool returns an isError result (the model sees the failure and reports it) instead of a false “done”. Success therefore means durability.
• The tool is health-gated: memory.write / memory.read are only advertised to the model when the memory sidecar is actually reachable. If the sink is down, the model doesn’t see a memory tool at all and degrades explicitly (“I couldn’t persist that”) rather than calling a dead endpoint and getting a phantom success. Because sidecars are container-scoped and persistent, any warm crew container keeps the tools available across runs.

​

2. Reading Memory (System Prompt Injection)

[AGENT MEMORY]
--- AGENT.md (long-term memory) ---
...agent's personal knowledge...
--- Daily log: 2026-04-14 (today) ---
...today's session notes...
[END AGENT MEMORY]

[CREW SHARED MEMORY]
--- CREW.md (crew-wide knowledge) ---
...crew conventions and decisions...
[END CREW SHARED MEMORY]

[MEMORY INSTRUCTIONS]
...instructions on how to write memory...
[END MEMORY INSTRUCTIONS]

​

2a. Operator model (per-user)

/crew/shared/.memory/users/{user_slug}.md

[OPERATOR MODEL]
This operator has worked with the crew before. The following profile was
distilled and merged across prior sessions — treat it as a hint about how
they prefer to work, not as a fact about who they are or what they want.
- timezone: UTC+1
- language: Czech
- tone: terse, technical
[END OPERATOR MODEL]

​

3. Searching Memory

# Search personal memory only
curl localhost:9119/memory/search \
  -d '{"query": "PostgreSQL", "scope": "agent"}'

# Search crew shared memory
curl localhost:9119/memory/search \
  -d '{"query": "deployment", "scope": "crew"}'

# Search both (merged by relevance)
curl localhost:9119/memory/search \
  -d '{"query": "database", "scope": "both"}'

​

Dynamic Budget Allocation

​

API reference

​

POST /memory/search

{
  "query": "database migration strategy",
  "limit": 10,
  "scope": "both"
}

{
  "results": [
    {
      "file": "AGENT.md",
      "snippet": "All DB migrations are in internal/database/migrate.go...",
      "score": -2.345,
      "source": "agent"
    },
    {
      "file": "CREW.md",
      "snippet": "Use PostgreSQL 16 for all new databases...",
      "score": -1.437,
      "source": "crew"
    }
  ],
  "count": 2
}

​

GET /memory/status?scope=agent|crew

{
  "total_files": 5,
  "total_chunks": 23,
  "indexed_at": "2026-04-14T14:30:00Z",
  "total_size_kb": 48,
  "search_ready": true
}

​

POST /memory/reindex?scope=agent|crew

​

CLI (Development & Debugging)

# Reindex agent memory
crewship memory reindex -p /path/to/agents/lead/.memory -S agent

# Search crew shared memory
crewship memory search "deployment" -p /path/to/crew-root -S crew

# JSON output for scripting
crewship memory search "PostgreSQL" -p /path -S crew -F json

​

Access Control

​

Limits

​

Load-time injection scan

--- Daily log: 2026-06-09 (today) ---
[BLOCKED: possible prompt injection in Daily log: 2026-06-09 (today) — category=prompt_injection pattern=ignore_previous_instructions; operator can inspect the file directly]

• The live file is never modified. The substitution happens only in the assembled prompt. The file on disk is left exactly as written so you can open it and judge the content yourself — the notice points you at the file rather than discarding anything.
• The label is preserved so you can tell which tier and which file produced the hit, and the category / pattern map back to the scanner rule.
• It is deterministic. The same file content always yields the same notice (first-hit, fixed rule order), so a blocked section won’t flicker between runs.

​

Memory write overflow guidance

• Hard cap exceeded (the write would push the tier past its cap): the result is an error, nothing is written, and the result metadata carries current_entries (the current on-disk body) and usage (e.g. 3900 of 4000 bytes, 97%). The message instructs the agent to consolidate the current entries — merge duplicates, drop stale lines, summarize — and retry the write in this turn with mode='replace' carrying the consolidated body.
• Soft cap (80%) crossed (the write succeeds but is close to the cap): the same current_entries + usage are attached and the warning steers the agent to consolidate and rewrite the consolidated body in this turn, before the next append is rejected.

​

Best Practices

​

Common pitfalls

• Crew reindex lags up to 60 seconds. The lead sidecar reindexes the crew tier on a 60-second tick. Writes to CREW.md or topics/*.md are searchable on the next tick, not immediately — if you need instant visibility, hit POST /memory/reindex?scope=crew from the lead’s sidecar.
• Agent-tier reindex after /memory/write is asynchronous. A successful POST /memory/write returns 201 the moment the bytes are durable on disk; the FTS5 reindex (and the memory.updated journal entry) then run on a single-worker background queue rather than blocking the response. The lag is sub-second in practice. The queue is strict FIFO, so consecutive writes to the same file reindex in write order — turn N always lands before turn N+1, never a stale earlier write winning a race. Writes are still searchable essentially immediately; if you need a hard barrier (e.g. write-then-search in a tight loop), the queue is drained on sidecar shutdown so nothing is lost, but for instant in-session visibility you can hit POST /memory/reindex?scope=agent.
• Single-agent crews have no crew tier. The crew scope returns 503 for an agent that isn’t a member of a crew (or whose crew has only itself). The budget for the agent tier is 100% in that case; no crew context to retrieve.
• Agents cannot read other agents’ personal memory — even within the same crew. Container bind mounts enforce this at the filesystem level, not by API check. If a workflow needs cross-agent state, the right surface is CREW.md or topics/, written by the lead.
• Budget is measured in characters, not tokens. The default 15,000-character budget is ~3,500–4,500 tokens depending on language and content. Don’t reason about budget as if it were tokens — the orchestrator slices on character boundaries.
• The 10 MB per-agent memory cap is a hard limit. Once a directory exceeds it, new writes fail rather than evicting old ones — consolidation isn’t automatic eviction. Curated facts only, not raw logs.
• Don’t delete AGENT.md entries casually. Memory is append-mostly. Remove only entries that are explicitly outdated — pruning live knowledge is what makes an agent feel “dumber than yesterday”.
• Migration v54/v55 must be applied for hybrid retrieval. Older databases that predate the Crew Journal era (PRs #211/#212) don’t have the importance_score, reference_count, or journal_entries_fts columns these endpoints read. Migrations apply automatically on crewship start, so start the upgraded binary once before depending on RRF scoring.
• Docker network Internal: true blocks sidecar → embedding model. If the agents network is Internal: true, the sidecar can read its on-disk FTS5 index but cannot reach a remote embedding service if one is configured, silently degrading hybrid retrieval to BM25-only. The fix lives in internal/provider/docker/docker.go:ensureNetwork — the network must be Internal: false with a gateway.

​

Related

• Episodic memory — the hybrid retrieval (RRF) + importance/decay/reinforce uplift from PRs #211/#212 that this guide builds on.
• Consolidate — the nightly worker that promotes recurring daily/*.md observations into AGENT.md / CREW.md and archives the original logs.
• Crew Journal — the event log behind the FTS5 mirror and the journal_embeddings table memory reads from.
• Keeper — where secrets belong instead of memory files (memory is not encrypted at rest).
• Orchestration — the runtime that calls BuildMemoryBlock to inject memory into system prompts at agent-run time.
• Skills — for agent-side packaged knowledge that doesn’t change per-user/per-crew; complementary to memory rather than overlapping.