Skip to content

phi-cyvl/gestalt

BranchesTags

Repository files navigation

aliases
Gestalt
Agent Infrastructure
Knowledge Base
tags
gestalt
infrastructure
agents
orchestration
memory
created 2025-02-25
updated 2026-04-02

Gestalt

Persistent knowledge and memory system for AI coding agents. Four-layer architecture that makes your agent smarter over time with zero manual effort.

Works with Claude Code and Cursor. Everything runs automatically after setup.

How It Works

sequenceDiagram
    participant You
    participant Claude as Claude Code
    participant Hook as Hooks
    participant Letta as Letta (Memory)
    participant Graphiti as Graphiti (Facts)
    participant Files as knowledge/*.md

    Note over You,Files: Session Start (automatic)
    Hook->>Letta: GET memory blocks
    Hook->>Claude: Inject preferences, context, pending items
    
    Note over You,Files: During Session
    You->>Claude: Ask questions, build things
    Claude->>Files: gestalt_search("deploy")
    Claude->>Graphiti: search_memory_facts("platform")
    
    Note over You,Files: Session End (automatic, 0.4s)
    Hook->>Letta: Send transcript (async)
    Hook->>Graphiti: Feed episode
    Hook->>Files: Write session summary
    
    Note over Letta: Letta updates memory blocks
    Note over Graphiti: Graphiti extracts entities + facts
Loading

Knowledge Consolidation

Gestalt's equivalent of Claude Code's AutoDream. Every 5 sessions, a nudge suggests running /consolidate to synthesize knowledge across all four layers.

flowchart TD
    subgraph Consolidate["/consolidate"]
        C1[Check Letta blocks<br/>for promotable facts] --> C2[Find missing<br/>cross-links]
        C2 --> C3[Query Graphiti for<br/>expired/stale facts]
        C3 --> C4[Update entries<br/>rebuild indices]
    end

    LETTA[Letta Memory Blocks<br/>project_context, pending_items] -->|promote| C1
    SEARCH[gestalt_search<br/>semantic similarity] -->|discover| C2
    GRAPHITI[Graphiti<br/>expired_at != null] -->|flag stale| C3
    C4 -->|write| KNOW[knowledge/*.md]
    C4 -->|feed| GRAPHITI
Loading
Trigger How
Manual Run /consolidate anytime
Auto-nudge SessionStart hook injects a reminder every 5 sessions

What consolidation does:

  • Promotes Letta learnings (architectural facts, patterns) into curated gestalt entries
  • Cross-links related entries that aren't [[wikilinked]] yet (discovered via semantic search)
  • Flags stale entries where Graphiti detected contradictions or expired facts
  • Rebuilds indices and feeds updates back to Graphiti

Four Memory Layers

graph TB
    subgraph Curated["Layer 1: Curated Knowledge (human-authored)"]
        K[knowledge/*.md<br/>39 entries] --> M[MANIFEST.md]
        K --> G[GRAPH.md]
        K --> S[SOURCES.md]
    end

    subgraph Episodic["Layer 2: Episodic Memory (Letta)"]
        L[8 Memory Blocks<br/>preferences, context,<br/>patterns, pending items]
        SS[Session Summaries<br/>~/.claude/memory/sessions/]
    end

    subgraph Temporal["Layer 3: Temporal Facts (Graphiti)"]
        GR[Entity Nodes<br/>repos, tools, patterns]
        GF[Fact Edges<br/>with validity windows]
        GR --- GF
    end

    subgraph Semantic["Layer 4: Semantic Search (SQLite)"]
        FTS[FTS5 BM25 Index]
        VEC[sqlite-vec Vectors]
        FTS --- VEC
    end

    K -.->|chunk + embed| Semantic
    L -.->|injected at<br/>session start| Curated
    GF -.->|staleness<br/>signals| Curated
Loading
Layer Storage Writes Reads Lifecycle
Curated knowledge/*.md /save, /learn, /review gestalt_read, file read Staleness detection
Episodic Letta (8 blocks) Auto via Stop hook Injected at SessionStart Letta manages
Temporal Graphiti (FalkorDB) Auto from sessions search_memory_facts Facts auto-invalidated
Semantic .search/gestalt.db Rebuilt on gestalt rebuild gestalt_search Disposable

Infrastructure

graph LR
    subgraph Docker["Docker Compose (systemd, starts on boot)"]
        LETTA[Letta Server v0.16.6<br/>port 8283<br/>Sonnet]
        FALK[FalkorDB<br/>port 6379]
        GRAPH[Graphiti MCP<br/>port 8000<br/>Sonnet + OpenAI]
    end

    subgraph Volumes["Named Docker Volumes"]
        LV[letta-data]
        LP[letta-pgdata]
        FV[falkordb-data]
    end

    subgraph Hooks["Claude Code Hooks"]
        SSH[SessionStart<br/>10s, command]
        STH[Stop<br/>30s, command]
    end

    subgraph MCP["MCP Servers"]
        GM[gestalt<br/>4 tools, stdio]
        GRM[graphiti-memory<br/>9 tools, HTTP]
    end

    LETTA --- LV
    LETTA --- LP
    FALK --- FV
    SSH -->|health + inject + auto-restore| LETTA
    STH -->|transcript async| LETTA
    STH -->|episode| GRAPH
    STH -->|block backup| LETTA
    GM -->|read + search| DB[(SQLite)]
    GRM -->|facts + nodes| GRAPH
Loading

Data persists in named Docker volumes (letta-data, letta-pgdata, falkordb-data). The SessionStart hook auto-restores from backups/ if volumes are empty or missing. The Stop hook snapshots Letta agent state + FalkorDB RDB after each session.

Backup & Recovery

Gestalt automatically backs up and restores its stateful services (Letta + FalkorDB) without any manual steps.

What Gets Backed Up

Artifact Tool Format Location
Letta agent state backup.sh .af archive backups/letta/
Letta memory blocks backup.sh JSON backups/letta/
FalkorDB knowledge graph backup.sh RDB snapshot backups/falkordb/

Retention

  • Latest backup always kept (overwritten each session)
  • Weekly snapshots retained for 4 weeks (timestamped)
  • Old snapshots pruned automatically

Encryption

Backups are encrypted at rest via git-crypt. The backups/** path is listed in .gitattributes and encrypted before any commit. The key lives at ~/.gestalt-keys/gestalt.key.

# One-time: unlock the repo after cloning
git-crypt unlock ~/.gestalt-keys/gestalt.key

Auto-Restore on Session Start

The SessionStart hook runs tools/restore.sh automatically when Letta or FalkorDB volumes are empty (e.g. after docker compose down -v, a machine wipe, or a fresh clone). No manual intervention needed — the hook detects missing data and restores from the latest backup before injecting memory.

Manual Operations

# Force a backup now
bash tools/backup.sh

# Force a restore from the latest backup
bash tools/restore.sh

# Restore from a specific weekly snapshot
bash tools/restore.sh backups/letta/letta-2026-03-30.af backups/falkordb/falkordb-2026-03-30.rdb

Getting Started

For New Users (Fork First)

Important: This repo contains knowledge entries, indices, and config specific to the original author's workspace. Fork it first so you can version-control your own data.

# 1. Fork on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/gestalt.git
cd gestalt

# 2. Reset to a clean slate (removes all user-specific data)
bash tools/reset-for-new-user.sh

# 3. Configure
cp .env.example .env
# Edit .env — add your ANTHROPIC_API_KEY and OPENAI_API_KEY

# 4. Install (one command, one sudo prompt)
sudo bash tools/install.sh

# 5. Open Claude Code in your workspace and start working
# Memory starts accumulating automatically

The reset script removes all knowledge entries, indices, API keys, and design docs while preserving the framework (commands, agents, rules, hooks, tools).

For Existing Users

cp .env.example .env    # add your API keys
sudo bash tools/install.sh

See SETUP.md for the detailed installation guide.

For Agents: Quick Reference

See AGENTS.md for concise agent-specific instructions.

MCP Tools

Gestalt (curated + semantic):

  • gestalt_search(query, limit) — hybrid BM25 + vector search
  • gestalt_read(slug) — read a knowledge entry
  • gestalt_manifest() — entry index
  • gestalt_graph() — data flow index

Graphiti (temporal):

  • search_memory_facts(query, group_ids, max_facts) — facts with validity windows
  • search_nodes(query, group_ids, max_nodes) — entity summaries
  • add_memory(name, episode_body, group_id, source) — add an episode

Reading Knowledge

flowchart LR
    Q[Question] --> M{Check MANIFEST.md}
    M -->|slug found| R[Read knowledge/slug.md]
    M -->|not sure| S[gestalt_search query]
    R --> W{Has wikilinks?}
    W -->|yes| R2[Follow links]
    W -->|no| A[Answer]
    S --> A
    R2 --> A
Loading
  1. Read MANIFEST.md — find the relevant slug
  2. Read knowledge/{slug}.md — follow [[wikilinks]]
  3. For data flow: read GRAPH.md
  4. For semantic search: gestalt_search("your topic")

Writing Knowledge

  • Authoritative voice — as if the correct answer was always known
  • [[wikilinks]] inline to reference other entries
  • ^block-id anchors on key facts
  • ## Data Flow sections for pipelines
  • 500-line cap per entry (split if larger)
  • Run gestalt rebuild after writing

Commands

Command What It Does
/gestalt Show status of all 4 memory layers
/recall <query> Query temporal knowledge graph
/consolidate Synthesize knowledge across layers (AutoDream equivalent)
/save Manual mid-session knowledge capture
/learn <repo> Deep-scan a repo with 4 parallel agents
/review Audit knowledge base against codebase
/investigate <topic> Deep investigation with parallel research
/build <spec> Build from description or spec
/implement <srs> Full SRS → ADR → SDD → Build → QA
/audit <path> Final quality gate with 4 specialist reviewers
/pr <number> Multi-persona PR review with selectable fixes
/discuss <topic> Structured critique with evidence
/help Full command index

Agent Definitions

graph TD
    subgraph Writers["Write Agents (sonnet)"]
        B[builder<br/>implements code]
        D[designer<br/>produces SDDs]
        R[researcher<br/>evaluates options]
    end

    subgraph Scanners["Scan Agents (haiku)"]
        L[learner<br/>deep-scans repos]
        RV[reviewer<br/>audits entries]
        V[verifier<br/>checks requirements]
        SY[syncer<br/>reconciles external]
        SD[staleness-detector<br/>checks git history]
    end

    O[Orchestrator<br/>you] -->|spawn| Writers
    O -->|spawn| Scanners
    Writers -->|results| O
    Scanners -->|findings| O
Loading

All multi-agent work uses the planner-worker hierarchy — the orchestrator spawns stateless workers in parallel, synthesizes their results, and makes all decisions.

CLI

./tools/gestalt search "ArgoCD deploy"   # semantic search
./tools/gestalt health                    # service status
./tools/gestalt rebuild                   # regenerate all indices
./tools/gestalt list                      # list all entries
./tools/gestalt graph mermaid             # data flow as mermaid

Configuration

All config in .env (gitignored). Template: .env.example.

Variable Required Default Purpose
GESTALT_WORKSPACE Yes — Where you open Claude Code/Cursor
ANTHROPIC_API_KEY Yes — Letta + Graphiti LLM inference
OPENAI_API_KEY Phase 2 — Graphiti embeddings (text-embedding-3-small)
LETTA_URL No localhost:8283/v1 Letta API endpoint
GRAPHITI_URL No localhost:8000 Graphiti MCP endpoint
GRAPHITI_GROUP_ID No gestalt Knowledge graph namespace
LETTA_MODEL No anthropic/claude-sonnet-4-6 Model for memory formation
LETTA_MODEL_FALLBACK No anthropic/claude-sonnet-4-6 Fallback if primary not recognized
GESTALT_STATE_DIR No $WORKSPACE/.claude/gestalt Agent ID, health log, lock file
GESTALT_SESSIONS_DIR No $WORKSPACE/.claude/memory/sessions Session summaries
GESTALT_TRANSCRIPTS_DIR No $WORKSPACE/.claude/memory/transcripts Transcript copies
GESTALT_VENV No $WORKSPACE/.claude/gestalt/venv Python venv for search tools
GESTALT_DIR No $WORKSPACE/gestalt Gestalt repo root
GESTALT_SESSION_RETENTION_DAYS No 7 Days to keep session summaries
GESTALT_LETTA_MAX_MESSAGES No 30 Max messages sent to Letta per session
GESTALT_LOCK_TIMEOUT No 60 Stop hook concurrent session lock (seconds)

File Layout

gestalt/                              ← fork this repo
├── .env.example                      ← config template
├── .env                              ← your config (gitignored)
├── docker-compose.yml                ← Letta + FalkorDB + Graphiti
├── knowledge/                        ← your curated entries
├── .search/gestalt.db                ← semantic index (gitignored)
├── MANIFEST.md                       ← auto-generated entry index
├── GRAPH.md                          ← auto-generated data flow
├── config/                           ← hook configs, statusline
├── .claude/
│   ├── hooks/                        ← SessionStart + Stop scripts
│   ├── commands/                     ← 25 slash commands
│   ├── agents/                       ← 8 agent definitions
│   ├── rules/                        ← always-on + glob rules
│   └── references/                   ← orchestration patterns
├── .cursor/                          ← Cursor equivalents
├── tools/
│   ├── install.sh                    ← one-command setup
│   ├── reset-for-new-user.sh         ← clean slate for new users
│   ├── gestalt                       ← CLI
│   ├── gestalt-mcp-server.py         ← unified MCP server
│   ├── gestalt-index-builder.py      ← semantic index builder
│   ├── enable-phase2.sh              ← Phase 2 activation
│   ├── backup.sh                     ← encrypted backup of Letta + FalkorDB
│   └── restore.sh                    ← auto-restore from backups
├── backups/                          ← git-crypt encrypted (letta/ + falkordb/)
├── templates/knowledge-entry.md      ← entry template
├── README.md                         ← this file
├── SETUP.md                          ← detailed install guide
└── AGENTS.md                         ← agent-specific instructions

Design Docs

Full requirements and design documentation in docs/pitches/gestalt-memory-expansion/:

  • index.md — pitch document
  • srs.md — software requirements specification
  • sdd/ — modular software design description (7 component docs)

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages