agent-memory

agent-memory is a Go memory-service layer for LLM agents and agent runtimes.

It stores durable memory with provenance, builds bounded context packets for LLM turns, records context/writeback history, and retrieves source-backed memory through a capability-gated hybrid RAG pipeline. The project is explicitly working toward a fully augmented RAG system: deterministic lexical/structured recall, vector semantic expansion, graph/GraphRAG contextual expansion, source rehydration, authority/sensitivity filtering, provenance, declared scoring, and eventually benchmarked model reranking where justified. It is deliberately not a plugin kernel, not an LLM provider, not a filesystem writer, and not a vector-database toy pretending similarity is truth.

What this repo owns

agent-memory owns memory semantics above an existing agent/plugin substrate:

• canonical memory records and artifacts;
• curated corpus snapshots;
• durable context-history events;
• raw trajectory events;
• operation proposals and admission/execution records;
• derived artifacts, embeddings, graph/index manifests, and health reports;
• retrieval planning, source rehydration, and degraded capability reporting;
• context packet construction/writeback surfaces;
• repo-local provider tool-skill declarations for inert proposal shaping.

It does not own:

• process/plugin supervision;
• generic agent planning/orchestration;
• model invocation;
• approval policy;
• credential storage;
• raw filesystem authority;
• direct SKILL.md materialization;
• treating summaries, embeddings, graph edges, vector rows, or model output as canonical truth.

The core rule

Canonical truth is narrow.

Everything else is evidence, working context, a derived index, or a candidate until admitted.

Class	Meaning
Canonical records/artifacts	Durable user/project truth.
Corpus snapshots	Durable reference material, not user/project truth.
Context history / raw trajectories	Searchable evidence of activity, not truth unless promoted.
Scratch/context packets	Bounded working context for tasks and LLM turns.
Derived artifacts / vector rows / graph edges	Retrieval/review aids, never truth by themselves.

Architecture at a glance

agent-core-system / agent runtime
        |
        v
agent-memory service API
        |
        +-- authority/read-scope/admission validation
        +-- service-owned PostgreSQL schema
        |     - canonical_records / canonical_artifacts
        |     - corpus_sources / corpus_snapshots
        |     - context_history_events / context_packet_manifests
        |     - raw_trajectory_events
        |     - operation_proposals / relation_records
        |     - derived_artifacts / index_manifests / audit_events
        |
        +-- hybrid retrieval planner
        |     - lexical + structured recall first
        |     - corpus/context/raw recall
        |     - relation graph expansion
        |     - pgvector semantic candidate recall when active
        |     - Apache AGE derived graph expansion when active
        |     - read-scope filtering
        |     - source rehydration
        |     - deterministic final shaping
        |
        +-- context packet + writeback coordinator
        +-- idle/review/health/candidate surfaces
        +-- repo-local tool-skills descriptors and Lua proposal shapers

Hybrid RAG / GraphRAG shape

The retrieval pipeline is coarse-to-fine and capability-gated:

1. Deterministic filtering first
   Lexical and structured recall run before expensive graph/vector work.

2. Vector as candidate expansion
   pgvector rows are derived locator artifacts keyed back to source ids. They are never truth by themselves.

3. Graph as contextual expansion
   Service-owned relation_records provide the fallback relation graph. Apache AGE can act as an optional derived graph sidecar when installed and manifested.

4. Final source-backed shaping
   Candidates are filtered by read scope/sensitivity/truth class, then rehydrated through source storage before final results are returned.

5. Visible degradation
   Missing vector/graph/corpus/context/raw capability produces degraded state. No channel may masquerade as active when its extension, graph/table, manifest, or model contract is missing or stale.

Current optional sidecars:

• src/internal/store/pgvector.go — pgvector sidecar support via github.com/pgvector/pgvector-go.
• src/internal/store/age_graph.go — Apache AGE derived graph sidecar support through fixed Cypher templates only.
• src/internal/store/hybrid_planner.go — PostgreSQL-backed adapter for the hybrid retrieval planner.
• docs/notes/hybrid-rag-reranking.md — ranking/scoring guidance.

Important limitation

The repository has safe/degraded tests for missing pgvector/AGE. Positive live extension evidence still requires a PostgreSQL fixture with pgvector and Apache AGE installed.

Until that exists, graph/vector optimization is implemented as optional capability-gated substrate, not as production-admitted benchmarked GraphRAG. The direction is still deliberate: this repo is being built toward fully augmented RAG, but every augmentation has to earn admission with source backing, degraded-mode behavior, benchmarks, and clear cost/security boundaries.

Provider diagnostics

Memory provider diagnostics are structured, redacted observability facts emitted through the inherited rpc-plugin-system SDK/helper path via src/internal/providerdiag. The repo keeps a narrow local sink/audit fallback for tests and non-SDK wiring, but the canonical provider path is the substrate SDK helper.

Safe facts are limited to provider/generation/capability/operation/correlation/status, bounded counts/sizes/durations, coarse degraded/error classes, and non-authoritative digest/version facts. Diagnostics must not carry raw corpus chunks, prompts, retrieval result bodies, context-packet item content, memory payloads, embedding vectors or source text, upstream bodies, authority refs, handles, sessions, provider-private paths, tokens, URLs, or reusable refs. Diagnostics are not canonical memory truth and never satisfy admission.

Tool-skills

Repo-local tool-skills live under tool-skills/.

They are descriptor/proposal surfaces only:

• they are not admitted by themselves;
• they grant no authority;
• Lua performs no I/O;
• Lua receives no denied content;
• raw SQL/Cypher/AGE/pgvector strings are rejected;
• filesystem/session/process/database/authority handles are rejected.

Declared surfaces include:

• memory.canonical.propose
• memory.retrieve
• memory.query.propose
• memory.graph.query
• memory.context_packet.build
• memory.skill_candidate.propose
• memory.health.check

See tool-skills/manifest.json and tool-skills/lua/*.lua.

Repository layout

docs/
  PRD.md
  architecture.md
  implementation-spec.md
  provider-bundle-constraints.md
  notes/

src/internal/
  authz/          admission/read-scope/audit primitives
  db/             migration runner and embedded PostgreSQL tests
  store/          PostgreSQL repositories, pgvector, AGE, hybrid planner adapter
  planner/        deterministic hybrid retrieval coordinator
  query/          safe MemoryQL parsing/planning
  service/        service API contracts and wiring
  contextsvc/     context packet/writeback coordinator
  ...             corpus, operations, retention, health, skills, etc.

tool-skills/
  manifest.json
  lua/

workflow/
  features/       scoped workflow records/evidence
  artifacts/      global coverage map

scripts/
  workflow-check.py

Dependencies

Canonical runtime: Go.

Current admitted dependencies:

• github.com/jackc/pgx/v5 — PostgreSQL connector.
• github.com/fergusstrange/embedded-postgres — disposable PostgreSQL integration tests.
• github.com/pgvector/pgvector-go — pgvector value encoding.

Python is not service implementation. python3 scripts/workflow-check.py is retained as workflow tooling only.

Verification

Run the full local gate:

gofmt -w $(find src -name '*.go')
go test -count=1 ./...
go build ./...
go vet ./...
luac -p tool-skills/lua/*.lua
python3 scripts/workflow-check.py
git diff --check

For routine read-only verification without rewriting files:

go test -count=1 ./...
go build ./...
go vet ./...
luac -p tool-skills/lua/*.lua
python3 scripts/workflow-check.py
git diff --check

Database behavior claims must be proven with Go tests through the admitted PostgreSQL connector. Static SQL inspection or fake repositories are not enough.

Current status

Implemented and tested in the Go service/library boundary:

• service-owned PostgreSQL schema and repositories;
• canonical record/artifact write paths;
• corpus source/snapshot paths;
• context history, packet manifests, model/tool writeback, raw trajectories;
• operation proposal/admission/execution records;
• derived artifacts and index manifests;
• hybrid retrieval planner wiring;
• optional pgvector sidecar;
• optional Apache AGE sidecar;
• tool-skills bundle safety tests;
• health/evaluation/retention/idle/skill candidate surfaces.

Still requiring extension-backed evidence before production GraphRAG admission:

• live pgvector ANN query tests;
• live Apache AGE graph creation/sync/traversal tests;
• vector-first graph expansion evidence;
• graph-first vector reranking evidence;
• EXPLAIN plans;
• benchmark/cost/latency evidence;
• declared scoring model implementation with ranking evidence;
• any learned/model reranker.

Canonical docs

Read these before changing behavior:

• docs/PRD.md — product boundary and acceptance criteria.
• docs/architecture.md — trust boundaries, data/control flow, and storage/retrieval architecture.
• docs/implementation-spec.md — concrete schemas, APIs, states, and verification requirements.
• docs/provider-bundle-constraints.md — memory-specific authority-use constraints.
• docs/notes/apache-age-pgvector-graphrag.md — PostgreSQL-native GraphRAG candidate notes.
• docs/notes/hybrid-rag-reranking.md — ranking/scoring and learned reranker admission guidance.

Development discipline

This repo uses workflow.toml as canonical development state. Feature records and evidence live under workflow/features/; the global coverage posture lives in workflow/artifacts/global-coverage-map.md.

Do not skip from vague product intent into implementation. Serious changes follow:

PRD -> architecture -> implementation spec -> feature decomposition -> implementation -> verification -> evidence

Do not hide behavior drift inside cleanup. Do not widen authority because it is convenient. Do not break userspace.