Memory

godotz.ai uses two complementary memory systems: Mnemopi for agent session memory (working, episodic, semantic tiers) and Knowledge Gardener v0.21.0 for structured project knowledge (a vaulted markdown corpus with automatic daily recaps).

Memory Tier Overview

┌───────────────────────────────────────────────────────┐
│  Working Memory      │  TTL: session lifetime          │
│  (Mnemopi)           │  Scope: current agent context   │
│                      │  Size: ~20 entries, auto-pruned  │
├───────────────────────────────────────────────────────┤
│  Episodic Memory     │  TTL: 7 days default            │
│  (Mnemopi)           │  Scope: agent + project          │
│                      │  Size: unlimited, scored recall  │
├───────────────────────────────────────────────────────┤
│  Semantic Memory     │  TTL: permanent                  │
│  (Mnemopi + KG)      │  Scope: global                   │
│                      │  Size: vault + knowledge graph   │
└───────────────────────────────────────────────────────┘

The three tiers are not siloed — Mnemopi promotes episodic entries to semantic when their recall count exceeds a threshold, and Knowledge Gardener ingests high-importance semantic entries into the vault.

Mnemopi

Working Memory

Working memory holds the current agent’s scratch state: decisions made, files read, tool results cached. It is in-context and ephemeral — discarded when the session ends.

# Store a working memory entry
omc retain "Using JWT RS256 because ES256 library not available on this node"

# Recall with semantic search
omc recall "JWT algorithm choice"
# → "Using JWT RS256 because ES256 library not available on this node"
#   relevance: 0.92 | age: 3m

Working memory auto-prunes: when the working set exceeds 20 entries, the lowest-scoring entries are evicted. The pruning score combines relevance, recency, and access frequency.

Episodic Memory

Episodic memory persists across sessions within a TTL window. It records agent decisions, outcomes, and context that should survive a restart.

# Stored automatically on session end for high-importance items
omc retain --importance 0.8 \
  "Deployed auth v2 to production at 14:32 UTC. No rollback needed."

# Surface relevant episodes in a new session
omc recall "auth deployment history"
# → [0.88] "Deployed auth v2 to production at 14:32 UTC..." (2d ago)
# → [0.71] "Auth v1 deployment failed due to Redis timeout" (14d ago)

Default TTL is 7 days; set --ttl 30d for longer retention. Items with importance ≥ 0.9 are retained permanently regardless of TTL.

Semantic Memory

Semantic memory holds durable facts that should persist indefinitely: architectural decisions, project invariants, user preferences, established conventions.

omc retain --importance 1.0 \
  "All agents must use omp/worker routing tag for GLM models. Never hardcode glm-* directly."

Semantic entries are never auto-evicted. They are promoted from episodic when the entry has been recalled three or more times.

Recall Mechanics

Mnemopi recall uses vector similarity search over entry embeddings, then re-ranks by a composite score:

recall_score = 0.5 * semantic_similarity
             + 0.3 * recency_weight
             + 0.2 * access_frequency

The recall tool returns entries above a 0.6 threshold by default. Pass --threshold 0.4 to widen the search.

Memory Lifecycle

store → score → persist
recall → vector search → re-rank → inject into context
review → decide: promote / invalidate / forget

omc recall "JWT"                    # surface relevant entries
omc memory-edit --id mem_42 \
  --op invalidate \
  "Superseded by new auth design"   # soft-delete with note
omc memory-edit --id mem_17 \
  --op forget                       # hard delete

Knowledge Gardener v0.21.0

Knowledge Gardener (developed by Kohei-Wada) maintains a structured markdown vault with automatic daily recaps. Unlike Mnemopi’s programmatic API, KG is file-based — agents and humans edit markdown files directly.

Vault Structure

The vault uses 9 standardized folders:

vault/
├── 00-inbox/           # Unprocessed captures, auto-cleared daily
├── 10-projects/        # Active project notes, one folder per project
├── 20-areas/           # Ongoing areas of responsibility
├── 30-resources/       # Reference material, how-tos, documentation
├── 40-archive/         # Completed projects, superseded notes
├── 50-decisions/       # Architecture decision records (ADRs)
├── 60-meetings/        # Meeting notes and action items
├── 70-recaps/          # Auto-generated daily recaps
└── 90-templates/       # Note templates for consistent structure

All nine folders must exist. KG refuses to run if any are missing. Initialize with:

kg init --vault ./vault

YAML Frontmatter Requirements

Every vault file must include frontmatter. KG ignores files without it and emits a warning:

---
title: JWT Refresh Token Design
date: 2026-06-07
tags: [auth, jwt, backend]
status: active          # active | draft | superseded | archived
importance: 0.8         # 0.0–1.0; controls recap inclusion
project: auth-v2        # must match a folder in 10-projects/
author: agent/codex     # agent ID or human handle
---

Required fields: title, date, status. All other fields are optional but strongly recommended.

Status values:

Auto-Recap

Knowledge Gardener runs a daily recap job at 06:00 UTC. It:

1. Scans all vault files modified in the past 24 hours
2. Filters to entries with importance >= 0.6
3. Groups by project and area
4. Generates a structured summary using the configured model
5. Writes the summary to 70-recaps/YYYY-MM-DD.md

---
title: Daily Recap 2026-06-07
date: 2026-06-07
status: active
importance: 0.9
---

# Daily Recap — 2026-06-07

## auth-v2
- Deployed JWT refresh token design (ADR-042)
- Fixed token expiry edge case (fix/token-expiry-edge-case)

## infra
- Redis cluster scaled to 3 nodes
- Cache hit rate improved to 47%

Recaps are themselves vault files and are included in future recaps if marked with importance >= 0.6.

Creating Notes

# Manual note
kg add --folder 50-decisions "ADR-042: JWT RS256 over ES256"

# From agent context (uses importance from Mnemopi entry)
kg capture --from-memory mem_42

# Template-based
kg add --template decision "ADR-043: Redis cluster topology"

Querying the Vault

kg search "JWT algorithm"           # full-text search across vault
kg search --tag auth                # filter by tag
kg search --status active --project auth-v2  # compound filter
kg show 50-decisions/ADR-042.md     # render a file
kg related 50-decisions/ADR-042.md  # find semantically related notes

Mnemopi–KG Sync

High-importance Mnemopi semantic entries (importance ≥ 0.85) are automatically synced to the vault’s 30-resources/ folder on a 6-hour cadence. Conversely, KG notes tagged #agent-memory are ingested into Mnemopi as semantic entries.

# kg.config.yaml
sync:
  mnemopi:
    enabled: true
    importanceThreshold: 0.85
    targetFolder: "30-resources"
    interval: "6h"
  reverseSync:
    enabled: true
    triggerTag: "agent-memory"

Choosing the Right Store

Related

• Architecture Overview — memory at L3 in the stack
• Self-Evolution — how memory drives pheromone trails
• Orchestration — agent memory in swarm context