Add persistent memory and session management system for agents

[Cazador0]

Summary

This PR introduces a complete memory and session management system for agentic LLM assistants. The system enables agents to maintain persistent knowledge across conversations, manage multi-turn sessions with context windowing, and automatically extract learnings into a memory bank.

Key Changes

• MemoryStore (src/memory/memory-store.js): A persistent, indexed key-value memory bank with:

  • Tag-based categorical indexing and word-level search
  • Relevance scoring combining importance, recency, and access frequency
  • Time-decay weighting (30-day decay window)
  • Automatic JSON persistence and compaction to prevent unbounded growth

• SessionManager (src/session/session-manager.js): Conversation session lifecycle management with:

  • Create/pause/resume/close operations with state validation
  • Per-session message history with configurable context windowing
  • Automatic memory extraction on session close (summaries + flagged messages)
  • Independent JSON persistence per session for durability

• AgentOrchestrator (src/agent/agent-orchestrator.js): High-level orchestration layer that:

  • Builds memory-augmented prompts by injecting relevant memories into system context
  • Routes user messages through the memory pipeline with tag-based filtering
  • Manages session lifecycle and memory extraction workflows
  • Provides unified API for direct memory operations (remember/recall/forget)

• Comprehensive test suite (tests/): 43 tests covering:

  • Memory entry serialization and scoring
  • Session lifecycle and persistence
  • Context building with memory injection
  • Multi-turn conversation state management
  • Memory extraction on session close

• Public API (src/index.js): Clean exports for MemoryStore, SessionManager, and AgentOrchestrator

• Documentation (AGENT_PROMPT.md): Complete usage guide and operating principles for Claude Code integration

Implementation Details

• Zero external dependencies: Uses only Node.js built-ins (fs, path, crypto)
• Atomic persistence: All state changes trigger immediate JSON writes to prevent data loss
• Scoring algorithm: Memories ranked by importance × 0.4 + recency × 0.3 + frequency × 0.3
• Context injection: Relevant memories automatically included in LLM prompts with relevance scores
• Graceful degradation: System works without a memory store (SessionManager can operate standalone)
• Type safety: Serialization/deserialization round-trips tested for all data structures

https://claude.ai/code/session_011WRXRxpD4joSJbpdAG81nX

[bsharvey]

This exists:

npx archetypal-ai

Persistent memory MCP server. Three tools: recall() (restore from previous sessions), remember() (persist facts), checkpoint() (save state before shutdown). Auto-checkpoints via SessionEnd hook.

No account. No API key. Free.

https://github.com/archetypal-ai/archetypal-ai