Skip to content

feat(memory): Add three-layer memory system with decision routing#113

Open
AmariahAK wants to merge 1 commit into
MiniMax-AI:mainfrom
AmariahAK:main
Open

feat(memory): Add three-layer memory system with decision routing#113
AmariahAK wants to merge 1 commit into
MiniMax-AI:mainfrom
AmariahAK:main

Conversation

@AmariahAK

Copy link
Copy Markdown

PR Description

i. What was the issue

Mini-Agent had a flat, single-layer memory system (SessionNoteTool + RecallNoteTool with a simple JSON store) and no structured decision routing. This limited the agent's ability to:

  • Maintain immutable project rules separate from learned patterns
  • Retain cross-session learnings with confidence gating
  • Auto-cleanup session-scoped context
  • Classify and route tasks by complexity (simple → direct, complex → think→plan→execute→verify→reflect→learn, conflict → confidence-weighted dispatch)

Issue #110 proposed a HeartFlow-inspired three-layer memory architecture and decision routing rules.

ii. Where was the issue

Layer Before After
mini_agent/tools/note_tool.py Flat JSON record/recall, no confidence Unchanged — remains as-is for backward compat
System prompt No memory guidance, no routing rules 53 new lines: Memory System + Decision Routing
Config No memory config MemoryConfig with enabled, core_memory_path, learned_confidence_threshold
CLI tool init No memory tools Three new tools registered alongside existing ones

iii. How did you fix it

New module mini_agent/memory/ — 5 files, all following existing architecture:

  • schema.py: MemoryEntry (Pydantic, confidence 0.0-1.0) + MemoryStore (JSON persistence, follows SessionNoteTool pattern)
  • manager.py: MemoryManager — CORE (read-only JSON), LEARNED (confidence-gated writes ≥0.7 threshold), EPHEMERAL (in-memory, reset() on session end)
  • tools.py: CoreMemoryTool, LearnedMemoryTool, EphemeralMemoryTool — all extend the existing Tool base class with name/description/parameters/execute → ToolResult

Config: MemoryConfig model added to ToolsConfig, parsed in from_yaml() following the MCPConfig pattern.

System prompt: New ## Memory System section (3 layers documented) + ## Decision Routing section (simple/complex/conflict routing with 6-step think→plan→execute→verify→reflect→learn cycle).

CLI: Memory tools registered in initialize_base_tools() with the existing green-checkmark pattern. EPHEMERAL reset called at session start and end.

iv. Why did you choose that method over others

  • Tools extend Tool base — zero changes to the Agent.run() loop. Tools are registered by name into self.tools dict, dispatched by the LLM automatically. No new infrastructure needed.
  • JSON storage — consistent with the existing SessionNoteTool pattern (load/save via MemoryStore.load_from_file / save_to_file). No new dependencies.
  • Config-driven — follows MCPConfig nested-model pattern with defaults, parsed in from_yaml(). Users can disable memory or tune thresholds without touching code.
  • Confidence gating at manager level — the MemoryManager.record_learned() returns (accepted: bool, reason: str), keeping the tool layer thin and the gating logic centralized.

v. How to test it locally

# Run the full memory test suite
uv run pytest tests/test_memory.py -v
# 19 tests: schema, manager, tool layers, confidence gating, ephemeral reset

# Verify config loads with memory defaults
uv run python -c "from mini_agent.config import Config; c = Config(api_key='test', model='test'); print(c.tools.memory)"
# Expected: MemoryConfig(enabled=True, core_memory_path='', learned_confidence_threshold=0.7)

# Verify memory tools appear in CLI (requires API key in config.yaml):
# uv run python -m mini_agent.cli
# Look for: ✅ Loaded Core Memory tool / Learned Memory tool / Ephemeral Memory tool

# Run full non-integration test suite
uv run pytest tests/ --ignore=tests/test_agent.py --ignore=tests/test_integration.py --ignore=tests/test_acp.py --ignore=tests/test_llm_clients.py --ignore=tests/test_llm.py --ignore=tests/test_session_integration.py -v

Implement CORE (immutable rules), LEARNED (confidence-gated cross-session patterns),
and EPHEMERAL (session-scoped, auto-cleared) memory layers with corresponding tools.
Add decision routing rules to system prompt for simple/complex/conflict task routing.

- New: MemoryEntry + MemoryStore Pydantic models (schema.py)
- New: MemoryManager managing three layers with confidence threshold gating
- New: CoreMemoryTool, LearnedMemoryTool, EphemeralMemoryTool (all extend Tool)
- New: MemoryConfig in config system with YAML parsing
- New: 19 comprehensive tests covering all layers and edge cases
- Updated: system_prompt.md with Memory System + Decision Routing sections
- Updated: cli.py registers memory tools, resets ephemeral on session end

Co-authored-by: atlarix-agent <agent@atlarix.dev>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants