memosq 1.0.0

Cross-agent persistent memory for AI coding assistants

OpenMemory

Cross-agent persistent memory for AI coding assistants.

OpenMemory is a lightweight, persistent memory system that enables AI coding assistants to remember context across sessions, share knowledge between different agents, and retrieve relevant past decisions through semantic search.

Features

• Zero-Config SQLite Storage — Auto-discovers project root, stores in .openmemory/memory.db
• Cross-Agent Compatibility — Works with Claude Code, Kilo Code, Antigravity, GitHub Copilot, Cursor, Codex, and any tool with shell access
• Semantic Search — Hash-based embeddings for finding related entries without heavy ML dependencies
• Automatic Context Loading — Injects project history into prompts via plugins for OpenCode, Kilo Code, Claude Code, and Antigravity
• Simple CLI — Log, search, and retrieve context with intuitive commands
• Lightweight — No heavy dependencies, runs offline, no API keys required

Quick Start

Installation

pip install memosq

Usage

# Log a decision
memosq log \
  --agent "claude-code" \
  --action "refactored" \
  --summary "Moved JWT validation to middleware" \
  --files "src/auth.ts,src/middleware.ts" \
  --decision "All auth logic should be centralized" \
  --tags "auth,security,middleware"

# Search memory
memosq search --query "authentication changes" --limit 5

# Get project context
memosq context

# Show recent entries
memosq recent --limit 10

# Filter by topic
memosq topic --name "auth" --limit 10

# Initialize OpenMemory for a project (creates .openmemory/ + configs)
memosq init --all

# Initialize with specific agent configs
memosq init --with-claude --with-cursor --with-kilo --with-git

Auto-Mode (opencode Integration)

OpenMemory includes a plugin for opencode that makes memory management completely automatic:

• Session Start: Automatically loads project context
• During Chat: Logs user prompts and assistant responses
• File Changes: Tracks code modifications automatically
• No Commands Needed: The user never touches the CLI

Enable Auto-Mode

Add to ~/.config/opencode/opencode.jsonc:

{
  "plugin": [
    "opencode-orchestrator",
    "memosq"
  ]
}

Auto-Mode (Kilo Code Integration)

Kilo Code is a fork of OpenCode and supports the same plugin system. OpenMemory includes a plugin for Kilo Code that makes memory management completely automatic:

• Session Start: Automatically loads project context
• During Chat: Logs user prompts and assistant responses
• File Changes: Tracks code modifications automatically
• No Commands Needed: The user never touches the CLI

Enable Auto-Mode

Add to ~/.config/kilo/kilo.jsonc:

{
  "plugin": [
    "opencode-orchestrator",
    "/Users/ege/Desktop/fikir/openmemory/plugin/kilo-memory-plugin.js"
  ]
}

Auto-Mode (Antigravity Integration)

Antigravity is Google's AI coding agent with SDK support. OpenMemory includes hooks for Antigravity that make memory management completely automatic:

• Session Start: Automatically loads project context
• During Chat: Logs user prompts and assistant responses
• File Changes: Tracks code modifications automatically
• No Commands Needed: The user never touches the CLI

Enable Auto-Mode

from google.antigravity import Agent, LocalAgentConfig
from memosq.antigravity import OpenMemoryHooks

hooks = OpenMemoryHooks()
config = LocalAgentConfig(
    hooks=hooks.get_hooks(),
    policies=hooks.get_policies()
)
async with Agent(config) as agent:
    response = await agent.chat("Hello")

Auto-Mode (Claude Code Integration)

Claude Code supports hooks that run automatically. OpenMemory includes hooks for Claude Code that make memory management completely automatic:

• Session Start: Automatically loads project context
• During Chat: Logs user prompts and assistant responses
• File Changes: Tracks code modifications automatically
• No Commands Needed: The user never touches the CLI

Enable Auto-Mode

Add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "memosq",
            "args": ["context"],
            "async": true
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "memosq",
            "args": ["log", "--agent", "claude-code", "--action", "user_prompt", "--summary", "{{prompt}}", "--tags", "prompt,claude"],
            "async": true
          }
        ]
      }
    ]
  }
}

Architecture

┌─────────────────────────────────────────────┐
│              AI Agent (Any)                  │
│  (Claude, Copilot, Cursor, Codex, etc.)     │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│           OpenMemory CLI / Plugin             │
│         (scripts/memosq.py)              │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│         OpenMemory Core Library               │
│         (memosq/__init__.py)             │
│                                              │
│  • SQLite Storage                             │
│  • Semantic Search (Hash-based Embeddings)   │
│  • Context Builder                            │
│  • Auto-discovery                             │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│         .openmemory/memory.db                │
│     (Shared across all agents in project)    │
└─────────────────────────────────────────────┘

Data Format

Each memory entry contains:

{
  "id": 1,
  "timestamp": "2026-06-11T01:20:02",
  "agent": "claude-code",
  "action": "refactored",
  "summary": "Moved JWT validation to middleware",
  "files": "src/auth.ts,src/middleware.ts",
  "decision": "All auth logic should be centralized",
  "outcome": "success",
  "tags": "auth,security,middleware",
  "embedding": "[0.12, 0.05, ...]"
}

Semantic Search

OpenMemory uses a lightweight hash-based embedding system:

• No ML dependencies — No PyTorch, TensorFlow, or transformers
• Offline — Works without internet or API keys
• Fast — 128-dim vectors computed in microseconds
• Effective — Shared vocabulary creates overlap between related entries

For production use, you can swap in sentence-transformers by overriding the _generate_embedding method.

Best Practices

1. Log decisions, not just actions — Include WHY, not just WHAT
2. Use consistent tags — Makes filtering and searching effective
3. Include file paths — Helps agents understand scope
4. Search before assuming — Check if similar work was done before
5. Update on failures — Log what didn't work and why

API Usage

from memosq import OpenMemory

# Initialize
memory = OpenMemory()

# Log an entry
memory.log(
    agent="claude-code",
    action="implemented",
    summary="Added rate limiting to API endpoints",
    files="src/middleware/rate-limit.ts",
    tags="api,security,performance"
)

# Search
results = memory.search("authentication changes", limit=5)

# Get recent entries
recent = memory.recent(limit=10)

# Get project context
context = memory.get_context()

# Get entries by topic
topic = memory.get_topic("auth", limit=10)

Storage

Memory is stored in .openmemory/memory.db at the project root. The database is auto-discovered by:

1. Looking for .openmemory/ in the current directory
2. Walking up the tree for .git/ or .openmemory/
3. Using the first found project root

This means all agents working on the same project share the same memory automatically.

Commands

Command	Description
memosq log	Create a new memory entry
memosq search	Semantic search across all entries
memosq recent	Show most recent entries
memosq context	Project summary and statistics
memosq topic	Filter by tag/topic
memosq init	Initialize OpenMemory for a project

Initialize

Run memosq init once per project to set up automatic memory:

# Basic setup (creates .openmemory/ + database)
memosq init

# Setup with all supported agent configs
memosq init --all

# Setup with specific agents
memosq init --with-claude --with-cursor --with-kilo --with-git

What init creates:

• .openmemory/ directory with memory.db SQLite database
• --with-claude → .claude/settings.json (auto-log hooks)
• --with-cursor → .cursorrules (logging instructions)
• --with-kilo → kilo.jsonc + .kilo/rules/ (config)
• --with-git → .git/hooks/post-commit (auto-log commits)
• --all → Enables all of the above

Contributing

See CONTRIBUTING.md for details.

Changelog

See CHANGELOG.md for version history.

License

MIT — see LICENSE

Related

• opencode — AI coding assistant
• OpenMemory Plugin — Auto-mode for opencode

---

Made for agents, by agents. 🧠