persistent-memory-core

Persistent Memory Core (PMC) is a memory layer for AI coding agents. It indexes your repositories into PostgreSQL + pgvector, records decisions, tasks, agent runs and lessons, and hands the right slice of that memory back to Claude Code, claude.ai, or any MCP client at the moment it is useful. GitHub stays the canonical source of truth; the database holds rebuildable derived memory.

Capabilities

• Hybrid retrieval — vector (HNSW) and full-text lanes fused with Reciprocal Rank Fusion, so exact identifiers and conceptual questions both land (ADR-030).
• Project memory — mission, milestones, prioritised tasks, decisions with rationale, issues, temporal facts, salience decay.
• Episodic lessons — lessons extracted from logged agent runs, embedded, deduplicated, reinforced when they help, injected before code.
• Ambient context — a compact context block for a prompt: lessons, relevant chunks, active tasks, recent decisions.
• Claude Code plugin — briefing on session start, ambient context on every prompt, automatic flush before compaction and at session end, search / brief / lessons / flush skills (plugins/pmc-memory/).
• MCP server — 33 tools over Streamable HTTP (/mcp) and SSE, bearer or OAuth 2.0 + PKCE for claude.ai, deployed on Cloud Run.
• Operations — Alembic migrations, pmc doctor (connectivity, schema invariants, embedding dimensions, Cloud Run reachability), production runbook, CI on four Python versions against pgvector.

Quick start (local)

Prerequisites: Docker Desktop, uv, git.

git clone https://github.com/aress2525/persistent-memory-core.git
cd persistent-memory-core
docker compose up -d                 # PostgreSQL 16 + pgvector on port 5434
uv sync --all-extras                 # runtime extras + dev group (tests need them)
cp .env.example .env                 # add OPENAI_API_KEY / ANTHROPIC_API_KEY
uv run alembic upgrade head          # schema
uv run pmc doctor                    # everything green?
uv run pmc add-project --key myproj --name "My project"
uv run pmc reindex --project myproj --repo-path ../my-repo
uv run pmc search --project myproj --query "connection pool"

scripts/bootstrap_local.{ps1,sh} does the same in one step. Without OPENAI_API_KEY the mock embedding provider is used (deterministic vectors, fine for tests, useless for real search). Full instructions, including macOS/Windows notes and production bootstrap: docs/INSTALL.md.

Using it with Claude Code

Install the plugin once, then every checkout that has a .pmc.json (or a registered git remote) gets memory automatically:

/plugin marketplace add aress2525/persistent-memory-core
/plugin install pmc-memory@pmc

Set PMC_API_KEY as a user-level environment variable (never in a settings file). In a checkout of this repository, claude --plugin-dir plugins/pmc-memory loads the plugin directly. What the hooks and skills do, and how to disable the per-prompt context: plugins/pmc-memory/README.md and the user manual.

For claude.ai, add the server as a custom connector at https://pmc-mcp-318538827786.us-central1.run.app/mcp (OAuth is discovered automatically): docs/CLAUDE_AI_SETUP.md.

CLI

The most used commands (uv run pmc --help lists all 60):

Architecture

• docs/ARCHITECTURE.md — the full picture.
• Five schemas: pmc_entity (projects, repositories, documents, chunks, decisions, tasks, issues, strategic memory, lessons), pmc_vector (embeddings), pmc_graph (edges), pmc_event (ingestion, retrieval, agent runs, mutations, sessions), pmc_policy (index policies).
• Packages: cli/ (Click commands by topic), mcp_server/ (tools/ and routes/, tools run off the event loop behind a bounded limiter), retrieval/ (vector, full-text, fusion, hydration, salience), plus single modules for stores, chunking, embedding providers, extraction, lessons.
• Configuration is one typed Settings object (config.py); os.environ is banned elsewhere. Alembic owns the schema; sql/cloudsql_bootstrap.sql only creates the extension and schemas.

Decisions are recorded as ADRs in docs/ (ADR-004 and ADR-005 were never written; numbering continues at 006). ADR-028 covers the uv toolchain and the async tool model, ADR-029 the Claude Code plugin, ADR-030 hybrid retrieval.

Python API

from persistent_memory_core.db import get_connection
from persistent_memory_core.reindex import reindex
from persistent_memory_core.retrieval import hybrid_search

with get_connection() as conn:
    reindex(conn, project_key="myproj", repo_path="../my-repo")
    for r in hybrid_search(conn, "myproj", "get_embedding_provider", top_k=5):
        print(r.file_path, r.metadata["vector_rank"], r.metadata["fts_rank"], round(r.score, 4))

Environment variables

Generated from Settings with uv run python scripts/dev/env_table.py. A .env in the working directory beats the process environment (local development is authoritative); production reads the injected environment. Set PMC_DOTENV_OVERRIDE=0 to reverse that for one process.

Deploying

Production is Cloud Run (pmc-mcp) + Cloud SQL (pmc-postgres, database pmc_prod) with secrets in Secret Manager. Migrations and rollouts go through scripts/migrate_prod.ps1 (proxy → alembic upgrade head → pmc doctor → optional -Deploy -ImageTag <sha>). The GitHub deploy.yml workflow only builds, pushes and deploys the image behind a production approval gate (once Workload Identity Federation is set up); it does not run migrations, so run the runbook's migrate step first for any release that adds a schema revision. Details, rotation, backups and troubleshooting: docs/ADMIN_MANUAL.md.

Project structure

persistent-memory-core/
  .claude-plugin/marketplace.json     # plugin marketplace (pmc-memory)
  .pmc.json                           # this repo's project key (pmc-self)
  alembic/versions/                   # 0001 … 0015, the schema source of truth
  plugins/pmc-memory/                 # Claude Code plugin: .mcp.json, hooks/, skills/, templates/
  scripts/                            # bootstrap, proxy, secrets, migrate_prod.ps1, dev/ probes
  sql/cloudsql_bootstrap.sql          # extension + schemas only
  src/persistent_memory_core/
    config.py                         # Settings (pydantic-settings), the only env reader
    cli/                              # pmc command groups
    mcp_server/                       # server.py, guard.py, readiness.py, tools/, routes/
    retrieval/                        # vector.py, fts.py, fusion.py, hydrate.py, hybrid.py, salience.py
    llm.py                            # structured-output LLM calls (Anthropic)
    embedding_provider.py             # OpenAI / local / mock providers
    entity_store.py, vector_store.py, graph_store.py, event_store.py
    reindex.py, chunking.py, github_ingest.py, policies.py
    extraction.py, episodic_rl.py, ambient.py, executive_cues.py, benchmarks.py, doctor.py
    integrations/, connectors/
  tests/                              # 300+ tests; `db` marker needs Docker pgvector
  docs/                               # manuals, architecture, ADRs, modernization plan

Documentation

• Installation · User manual · Admin manual
• Architecture · Multi-project · Multi-machine · Security · HIPAA · Data retention
• Modernization plan and status · Changelog

License

MIT