Skip to content
Moneypenny

Memory & Facts

Moneypenny’s memory system gives agents durable, structured knowledge that persists across sessions and compresses intelligently to fit context windows.

Because Moneypenny exposes its full surface area via MCP (Model Context Protocol), you can manage facts through the CLI, through natural language in any MCP-compatible client (Claude Desktop, Cursor, etc.), or programmatically via the sidecar interface.

What Is a Fact?

A fact is a unit of long-term memory with three compression levels:

LevelFieldExample
Fullcontent”The deployment pipeline uses ArgoCD with lint, unit tests, integration tests, canary (5% traffic for 30 minutes), then full rollout. Deploys Tue/Thu.”
Summarysummary”ArgoCD pipeline: lint-test-canary(5%/30min)-rollout Tue/Thu”
Pointerpointer”DEPLOY: argo-pipeline”

Each fact also carries:

  • confidence — 0.0 to 1.0, grows when re-extracted
  • keywords — space-separated terms for FTS matching
  • compaction_level — tracks how compressed this fact is in context
  • version — increments on updates
  • scope — private, shared, or protected

How Compression Works

When assembling context for an LLM call, Moneypenny loads all facts as pointers first (~2K tokens for 500 facts). As the token budget allows, it expands the most relevant facts to summaries, then to full content.

If the context window fills up, facts compact progressively: full text → summary → pointer. The agent can always expand a pointer to retrieve the full content.

Token budget: 128K
  ├── System prompt           ~500 tokens
  ├── Session history         ~8K tokens
  ├── Facts (all as pointers) ~2K tokens
  ├── Relevant facts expanded ~4K tokens
  ├── Knowledge chunks        ~6K tokens
  └── Current message         ~remaining

Adding Facts

Facts are added automatically by the extraction pipeline after each conversation turn, or manually:

Terminal window
mp facts add \
  --content "API rate limit is 1000 req/min per tenant." \
  --summary "API rate limit: 1000 req/min/tenant" \
  --pointer "API: rate-limit" \
  --confidence 0.95 \
  --keywords "api rate limit tenant"

Automatic Extraction

After each conversation turn, an extraction pipeline runs:

  1. Take the last few messages from the session
  2. Load existing facts to avoid duplicates
  3. Ask a small model to identify new durable knowledge
  4. Store extracted facts with confidence scores

Extraction can run on a cheap local model while the main conversation uses a larger API model. Memory management stays fast and local.

Listing and Inspecting

Terminal window
mp facts list
mp facts inspect <fact-id>

inspect shows the full record with audit history.

Expand a compacted pointer back to its full content:

Terminal window
mp facts expand <fact-id>

Searching Facts

Terminal window
mp facts search "deployment pipeline"

This uses the unified search system — FTS5 full-text matching plus vector KNN when embeddings exist, fused via Reciprocal Rank Fusion.

Updating Facts

Facts are versioned. When the extraction pipeline re-encounters a known fact with updated information, it creates a new version. The old version is superseded but retained for audit.

Deleting Facts

Terminal window
mp facts delete <fact-id> --confirm

Deletion is a soft operation — the fact is marked superseded but remains in the database for audit purposes.

Compaction Management

Reset compaction to restore full text in context:

Terminal window
mp facts reset-compaction <fact-id>
mp facts reset-compaction --all --confirm

Scoped Facts

Facts have a visibility scope:

  • private — visible only to the owning agent (default)
  • shared — visible to all agents after sync
  • protected — visible only to agents above a trust threshold

Promote a fact to shared scope:

Terminal window
mp facts promote <fact-id> --scope shared

Scope is enforced at the SQL level — agents cannot query outside their authorization boundary.