Postnesia

A persistent memory system for AI agents. Stores memories, journal entries, and tasks in a local SQLite database with vector search powered by Gemini embeddings.

Packages

| Package | Description | |---|---| | @postnesia/db | SQLite database, migrations, embeddings, raw query helpers | | @postnesia/mcp | MCP server — exposes all tools over stdio for MCP-capable agents | | @postnesia/cli | Commander CLI — direct tool access when no MCP connection is available | | @postnesia/hooks | Session bootstrap hooks — injects L1 memory context at session start |

Setup

1. Install in your agent's workspace

npm install postnesia
# or
pnpm add postnesia

This installs all packages (@postnesia/db, @postnesia/mcp, @postnesia/cli, @postnesia/hooks) as a single dependency.

2. Create a .env file

Create a .env in your workspace root with the absolute path to where the SQLite database should live:

DATABASE_URL="file:///absolute/path/to/your/workspace/memory.db"
GEMINI_API_KEY="your-gemini-api-key"
EMBEDDING_MODEL="gemini-embedding-001"
EMBEDDING_DIMENSIONS="768"
ANTHROPIC_API_KEY="your-anthropic-api-key"

DATABASE_URL must be an absolute file:// URL. Use the full path to a memory.db file in your workspace root.

3. Get a Gemini API key

1. Go to Google AI Studio
2. Create an API key
3. Ensure the Gemini Embedding API is enabled for your project
4. Add the key to your .env as GEMINI_API_KEY

4. Run migrations

This copies schema.prisma from the package into your project and runs prisma migrate dev to create the database tables:

npx postnesia-migrate-init

5. Seed core memories

Seeds the operational guide into the database as a core memory so the agent always knows how to use the system:

npx postnesia-seed

Agent Integration

MCP server (preferred)

Add the MCP server to your agent's MCP config:

{
  "mcpServers": {
    "postnesia": {
      "command": "npx",
      "args": ["postnesia-mcp"],
      "env": {
        "DATABASE_URL": "file:///absolute/path/to/your/workspace/memory.db",
        "GEMINI_API_KEY": "your-gemini-api-key",
        "EMBEDDING_MODEL": "gemini-embedding-001",
        "EMBEDDING_DIMENSIONS": "768"
      }
    }
  }
}

Session bootstrap hook (Claude Code)

Add to .claude/settings.json to inject L1 memory context at every session start and to checkpoint the conversation into a journal entry before context compaction:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx postnesia-claude"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx postnesia-compact"
          }
        ]
      }
    ]
  }
}

The PreCompact hook reads the conversation transcript, summarises it with Claude Haiku, and writes a journal entry plus any notable memories to the database before the context window is compacted. Requires ANTHROPIC_API_KEY in the environment.

CLI fallback (no MCP)

If no MCP connection is available, use the postnesia CLI directly via Bash:

# Memory
postnesia memory search "<query>" [--limit N]
postnesia memory add "<content>" --type <type> --importance <1-5> --tags "<t1,t2>" [--core]
postnesia memory update-core <id> --content "<content>" --content-l1 "<summary>"
postnesia memory recent [--hours N] [--limit N]
postnesia memory stats
postnesia memory consolidate
postnesia memory relationships <id>
postnesia memory link <fromId> <toId> --type <type>
postnesia memory unlink <relationshipId>

# Journal
postnesia journal add <YYYY-MM-DD> "<content>" [--learned "..."] [--key-moments "..."] [--mood "..."]
postnesia journal recent [--days N]

# Tasks
postnesia task create "<title>" [-d "<description>"] [-s <session-id>]
postnesia task update <id> [-s <status>] [-t "<title>"]
postnesia task list [--status <status>] [--session-id <id>]

Memory Types & Importance

| Type | When to use | Importance | |---|---|---| | decision | User makes a choice or picks an approach | 5 | | preference | How the user wants things to work | 5 | | person | Personal insight about the user | 5 | | lesson | Something failed then succeeded, or a better approach found | 3–5 | | technical | System config, API behaviour, implementation detail | 3–4 | | event | Session summary, milestone, notable event | 1–4 |

Relationships

Memories can be linked to form a knowledge graph. Relationships affect importance scoring — well-connected memories receive a boost during consolidation.

Auto-linking

When a memory is created via memory_add, the system automatically finds semantically similar existing memories (vector distance < 0.4) and inserts related edges. A supersedes edge is also inserted when supersedes_id is provided.

Relationship types

| Type | Meaning | |---|---| | related | Semantically similar — auto-created on memory_add | | supersedes | This memory replaces an older one — auto-created when supersedes_id is set | | supports | This memory provides evidence for another | | contradicts | This memory conflicts with another | | derives_from | This memory was derived from or inspired by another |

Manual linking (MCP)

memory_link(fromId, toId, type)   # create a typed edge
memory_unlink(relationshipId)     # remove an edge by its ID
memory_relationships(memoryId)    # view all edges for a memory

Manual linking (CLI)

postnesia memory link <fromId> <toId> --type <type>
postnesia memory unlink <relationshipId>
postnesia memory relationships <id>

Session Start Checklist

1. Resume open tasks: task_list(status="pending", session_id="<project>")
2. Search for lessons: memory_search("lesson")
3. Review recent context if needed: memory_recent(hours=24)

Database Migrations

# Apply pending migrations
npx postnesia-migrate-dev

# Create a new migration from schema changes
npx postnesia-migrate-dev --name <migration-name>

# Copy schema + run migrate dev (first-time setup)
npx postnesia-migrate-init