aaronrene / knowtation public
MEMORY-AUGMENTATION-PLAN.md markdown
126 lines 4.9 KB
Raw
sha256:65ccb454656ea5acdea0a10e559b78bcde1eb6ff753ecc2911bc99d1c3d7cadd feat(calendar): enforce agent context tiers in retrieval AP… Human minor ⚠ breaking 1 day ago

Memory Augmentation — Phase 8 Implementation

Phase 8 expands Knowtation's memory layer from a minimal 2-key JSON file stub to a multi-tier memory system with timestamped event log, optional vector-backed semantic recall, Mem0 API provider support, full CLI/MCP/hosted surface, and privacy controls.

Architecture

Three-Tier Provider System

Provider Config value Storage Semantic recall Dependency
file (default) memory.provider: file memory/{vault_id}/events.jsonl + state.json No (key lookup only) None
vector memory.provider: vector Same JSONL + embeddings in existing vector store Yes — memory_search Existing embedding infra
mem0 memory.provider: mem0 Delegates to Mem0 API at memory.url Yes (Mem0 built-in) External Mem0 instance

Storage Layout

  • Event log (events.jsonl): Append-only JSONL, one event per line. Never silently overwritten.
  • State overlay (state.json): Latest event per type for O(1) lookup.
  • Per-vault isolation: {data_dir}/memory/{vault_id}/
  • Hosted per-user: {DATA_DIR}/memory/{sanitizedUserId}/{vaultId}/

Event Taxonomy

Type Trigger Auto-captured by default
search After search Yes
export After export Yes
write After note write Yes
import After import Yes
index After re-index Yes
propose After proposal Yes
agent_interaction MCP tool call No (opt-in)
capture After inbox capture No (opt-in)
error On failure No (opt-in)
session_summary Explicit/periodic No (opt-in)
user Manual store Always allowed

Configuration

memory:
  enabled: true
  provider: file          # file | vector | mem0
  url: null               # for mem0 provider; env KNOWTATION_MEMORY_URL
  retention_days: null     # null = forever; number = auto-prune
  capture:                 # which events to auto-capture (default below)
    - search
    - export
    - write
    - import
    - index
    - propose

CLI Commands

Command Description
memory query <key> Read latest value for event type
memory list List recent events. --type, --since, --until, --limit, --json
memory store <key> <value> Store user-defined entry (type=user)
memory search <query> Semantic search (vector/mem0 only)
memory clear Clear events. --type, --before, --confirm required
memory export Export log. --format jsonl\|mif, --since, --until, --type
memory stats Event counts, storage size, oldest/newest

MCP Tools

Tool Description
memory_query Read latest value for a key
memory_store Store a value (agent write-back)
memory_list List events with filters
memory_search Semantic search (vector/mem0)
memory_clear Clear with confirmation

MCP Resources

URI Description
knowtation://memory/ Summary: enabled, provider, event counts
knowtation://memory/events Recent event log (last 50)
knowtation://memory/last_search Latest search memory
knowtation://memory/last_export Latest export memory

Hosted Path

  • Gateway: /api/v1/memory/* routes proxy to bridge
  • Bridge: Implements memory with per-user/vault file storage under DATA_DIR/memory/{userId}/{vaultId}/
  • Auth: All routes require JWT; X-Vault-Id header for multi-vault scoping

Privacy and Security

  • Per-user isolation on hosted (sanitized userId + vaultId partitioning)
  • Secret detection: storeMemory rejects data with common secret key patterns
  • Configurable capture types via memory.capture
  • memory clear requires --confirm
  • Memory entries store metadata, not full note bodies
  • Retention limits via memory.retention_days

Files

Core Library

  • lib/memory-event.mjs — Event types, ID generation, validation, secret detection
  • lib/memory-provider-file.mjs — File provider (JSONL + state.json)
  • lib/memory-provider-vector.mjs — Vector provider (extends file with embeddings)
  • lib/memory-provider-mem0.mjs — Mem0 API provider
  • lib/memory.mjs — MemoryManager class + backward-compatible wrappers

CLI

  • cli/index.mjs — Expanded memory subcommand with 7 actions

MCP

  • mcp/tools/memory.mjs — 5 MCP tools
  • mcp/resources/register.mjs — Memory resources
  • mcp/resources/metadata.mjs — Resource builders

Hosted

  • hub/gateway/server.mjs — Memory proxy routes
  • hub/bridge/server.mjs — Memory endpoints with per-user storage

Tests

  • test/memory.test.mjs — Core engine tests (46 tests)
  • test/memory-cli.test.mjs — CLI integration tests (14 tests)
  • test/memory-mcp.test.mjs — MCP resource tests (9 tests)
  • test/memory-hosted.test.mjs — Hosted isolation tests (11 tests)
File History 2 commits
sha256:65ccb454656ea5acdea0a10e559b78bcde1eb6ff753ecc2911bc99d1c3d7cadd feat(calendar): enforce agent context tiers in retrieval AP… Human minor ⚠ 1 day ago
sha256:9103f98c89257ed2b01c237cea895dabb3e85ea337dccb1161c175e4422355b6 docs: accept Calendar Events v0 spec with Phase 0 security … Human 1 day ago