cervellaswarm-session-memory

Git-native, human-readable session memory for AI agents.

Every decision is a commit. Every state is Markdown. Every audit trail is a git log away.

Session 1          Session 2          Session 3
   |                  |                  |
   v                  v                  v
+-----------+    +-----------+    +-----------+
| State.md  |--->| State.md  |--->| State.md  |
| (v1)      |    | (v2)      |    | (v3)      |
+-----------+    +-----------+    +-----------+
   |                  |                  |
   v                  v                  v
  git commit        git commit        git commit

No vector databases. No cloud services. No embedding models.

Why This Exists

AI agent frameworks lose context between sessions. Your agent forgets decisions, repeats mistakes, and can't explain what happened yesterday.

Current solutions store memory in opaque binary formats (LanceDB, ChromaDB, Qdrant) that you can't read, can't version-control, and can't audit.

cervellaswarm-session-memory takes a different approach: plain Markdown files tracked in git.

Installation

pip install cervellaswarm-session-memory

Requires Python 3.10+. Single dependency: pyyaml.

Quick Start

Initialize a project

cervella-session init my-project

This creates:

.session-memory/
  my-project/
    SESSION_STATE_my-project.md    # Your session state
    archive/                        # Old states go here
PROJECT_COMPASS.md                  # Project direction

Check quality

cervella-session check my-project

Scores your session state on 4 criteria (0-10 scale):

• Actionability (30%): Are there clear TODOs and next steps?
• Specificity (30%): Dates and numbers, or vague "soon" and "maybe"?
• Freshness (20%): Updated this week, or gathering dust?
• Conciseness (20%): Within line limits, or a novel?

Audit for secrets

cervella-session audit .session-memory/

Detects accidentally committed API keys, tokens, passwords, and private keys. Supports custom patterns via config.

Verify sync status

cervella-session sync my-project

Checks freshness, file size limits, git tracking, and uncommitted changes.

List projects

cervella-session list

Python API

from cervellaswarm_session_memory import (
    init_project,
    check_quality,
    audit_directory,
    verify_project,
    discover_projects,
)

# Initialize
project = init_project("my-project", project_root=Path("/path/to/repo"))

# Quality check
result = check_quality(project.state_file, project.name)
print(f"Score: {result.total}/10 [{result.status}]")

# Secret audit
audit = audit_directory(Path(".session-memory"))
assert audit.clean, f"Found {audit.critical_count} critical secrets!"

# Sync verification
sync = verify_project("my-project")
print(f"Overall: {sync.overall.value}")

# Discovery
projects = discover_projects()
for p in projects:
    print(f"  {p.name}: {p.state_file}")

Configuration

Create .cervella/session-memory.yaml in your project root:

# Where session memory files live
memory_dir: ".session-memory"

# File size limits
max_lines: 300
warning_lines: 200

# Quality scoring weights (must sum to 1.0)
quality:
  weights:
    actionability: 0.30
    specificity: 0.30
    freshness: 0.20
    conciseness: 0.20
  target_score: 8.0

# Secret scanning
secrets:
  extra_patterns:
    - pattern: "CUSTOM_KEY_[a-zA-Z0-9]+"
      name: "Custom API Key"

# Multi-project registry
projects:
  my-app:
    path: ~/Developer/MyApp
  my-api:
    path: ~/Developer/MyAPI

Config priority: CERVELLASWARM_SESSION_MEMORY_CONFIG env var > project .cervella/session-memory.yaml > user ~/.claude/session-memory.yaml > defaults.

How It Compares

Honest note: CrewAI and AutoGen offer semantic search over memory using vector embeddings, which we deliberately don't include. If you need similarity-based retrieval, pair this package with cervellaswarm-code-intelligence or use a vector store alongside it. Our bet is that explicit, human-curated session state is more reliable than automated extraction for critical decisions.

Template System

Session state files are created from templates with {{ placeholder }} substitution. The built-in templates provide a battle-tested structure for tracking:

• Session progress: What was done, what's next
• Decisions: What was decided, why, and when
• Project status: Progress bars and phase tracking
• Archive: Historical session summaries

JSON Output

All CLI commands support --json for integration with CI/CD and automation:

cervella-session check --json | jq '.[] | select(.total < 8)'

License

Apache-2.0. See LICENSE for details.

Part of CervellaSwarm

This package is part of the CervellaSwarm multi-agent framework. Other packages:

• cervellaswarm-code-intelligence - AST-based code analysis
• cervellaswarm-agent-hooks - Lifecycle hooks for Claude Code agents
• cervellaswarm-agent-templates - Agent definition templates
• cervellaswarm-task-orchestration - Deterministic task routing
• cervellaswarm-spawn-workers - Worker process management