vera-memory

A minimal structured memory layer for Vera.

Purpose

vera-memory stores and retrieves structured memories for Vera. It is intentionally small:

• active use only
• SQLite + FTS5
• structured records
• explicit CRUD and search tools
• automatic Project Ledger summary projection before agent start
• no automatic broad memory retrieval injection
• no automatic writeback
• no maintenance / review / cleanup pipeline
• no vector database
• no embeddings

Registered surface

Tools

• memory_remember
• memory_search
• memory_update
• memory_forget
• memory_status

Command

• /memory

Hooks

• session_start
• before_agent_start
• session_shutdown

Project Ledger prompt projection

On before_agent_start, vera-memory reads project-scoped ledger records for:

• project.overview
• project.plan
• project.progress
• project.constraints

It appends those summaries as a compact ## Project Ledger markdown block to the active system prompt. This is prompt-time projection of fixed project ledger identities only; ordinary memory search, writes, updates, and deletes still happen through explicit tools.

Data model

Core storage uses:

• meta
• memories
• memories_fts

See repository design docs for the exact V1 schema.

Config

Loaded from:

• agent/config/memory.json
• project .pi/config/memory.json

Minimal example:

{
  "enabled": true,
  "database": {
    "path": "../state/memory.sqlite"
  },
  "defaults": {
    "shortTtlDays": 14
  }
}

Notes:

• relative database.path values are resolved from the config file directory
• config is merged in order: built-in defaults, agent/config/memory.json, then project .pi/config/memory.json; project values override agent values, and unspecified nested database / defaults keys inherit from earlier layers
• if no config file exists, built-in defaults are used
• memory_remember does not do upsert

Project override example:

{
  "defaults": {
    "shortTtlDays": 30
  }
}

This project config changes only the short-memory TTL and inherits the database settings from the agent config or built-in defaults.

Behavior

Ordinary memory search and writes are manual; Project Ledger prompt projection is automatic.

• search only when memory may materially improve continuity or correctness
• store only stable, reusable information
• update only when the same stable object changed
• forget only on explicit request, confirmed error, or clear replacement
• Project Ledger summaries may be present in the system prompt without a memory_search call
• files, runtime state, and docs override memory

Smoke

Run:

npm run smoke

The smoke test covers the minimal V1 path:

• tool registration
• remember
• search by query
• search by identity
• update
• forget
• status

Loaded through agent/settings.json as ./packages/vera-memory.