What is a Memory

A memory is a typed, structured record that captures a unit of project knowledge — a decision, a pattern, an incident root cause, an architecture constraint — and makes it searchable by meaning, not keyword. Memories replace the static CLAUDE.md and .cursorrules files that load everything at session start regardless of what the agent actually needs.

Where a flat file forces your agent to ingest the entire document every session, Neuroloom surfaces only the memories relevant to the current task. A session focused on database query optimization retrieves discovery and architecture memories. A session debugging a failing test retrieves incident and discovery memories. The retrieval is semantic — it matches meaning, not exact text.

The Memory Record

Each memory is stored as a structured record with the following fields.

Memory Types

Every memory carries a memory_type that defines what kind of knowledge it represents. The type drives context injection — when a session begins, Neuroloom surfaces memories whose type matches the work pattern it detects.

Neuroloom uses 9 canonical types: 7 that the LLM assigns during extraction, and 2 that are system-only.

LLM-assignable types

System-only types (never LLM-assigned)

Memory Anatomy

A memory record has three distinct layers: its content (title and narrative), its classification (type, tags, concepts), and its scoring metadata (importance, confidence, PageRank).

The embedding is computed from the title and narrative at write time and used for all semantic search operations. The concepts field contains extracted semantic concepts that supplement embedding-based similarity with explicit concept overlap matching.

Living Knowledge vs. Static Files

The difference between Neuroloom memories and flat project-knowledge files is not just format — it is the retrieval model.

The dimensions that matter most for coding agents: whether the memory system tracks why something changed (supersedes), whether it can tell you how confident a memory still is, and whether it roots memories in actual code structure rather than prose descriptions of code.

A 500-line CLAUDE.md loads all 500 lines every session. Neuroloom injects the 8–12 memories most relevant to the task currently in front of the agent. As the project grows, context quality stays constant.

Storing a Memory

Store a memory by posting to the memories endpoint with a type and narrative.

curl -X POST https://api.neuroloom.dev/api/v1/memories \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Database migration strategy — always use Alembic autogenerate",
    "narrative": "All schema changes go through Alembic autogenerate. We ran into drift twice using manual migrations. The rule: never edit the migration file directly after generation; if the autogenerated migration is wrong, fix the model and regenerate.",
    "memory_type": "convention",
    "tags": ["database", "migrations", "alembic"],
    "source_files": ["alembic/env.py", "alembic/versions/"]
  }'

The API returns the created memory record including its assigned memory_id and initial scoring fields.

Searching Memories

Semantic search returns memories ranked by embedding similarity to the query, filtered by workspace.

curl -X POST https://api.neuroloom.dev/api/v1/memories/search \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how do we handle database schema changes",
    "limit": 5
  }'

The query "how do we handle database schema changes" returns the Alembic convention memory above even though the query does not use the words "Alembic", "autogenerate", or "migrations" — the semantic embedding matches meaning.

Related Pages

• Memory Lifecycle — how a memory moves from raw observation to enriched, scored record
• Memories API Reference — full endpoint documentation
• Claude.md Migration Cookbook — convert static project knowledge to typed memories