Metadata-Version: 2.4
Name: memosq
Version: 1.0.0
Summary: Cross-agent persistent memory for AI coding assistants
Project-URL: Homepage, https://github.com/yourusername/memosq
Project-URL: Documentation, https://github.com/yourusername/memosq#readme
Project-URL: Repository, https://github.com/yourusername/memosq
Project-URL: Issues, https://github.com/yourusername/memosq/issues
Author: OpenMemory Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,assistant,coding,context,memory,semantic-search,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# OpenMemory

Cross-agent persistent memory for AI coding assistants.

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**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

```bash
pip install memosq
```

### Usage

```bash
# 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](https://opencode.ai) 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`:

```json
{
  "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](https://kilo.ai) 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`:

```json
{
  "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](https://github.com/google-antigravity/antigravity-sdk-python) 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

```python
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](https://claude.ai) 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`:

```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

```python
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:

```bash
# 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](CONTRIBUTING.md) for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

## License

MIT — see [LICENSE](LICENSE)

## Related

- [opencode](https://opencode.ai) — AI coding assistant
- [OpenMemory Plugin](https://github.com/yourusername/openmemory/tree/main/plugin) — Auto-mode for opencode

---

**Made for agents, by agents.** 🧠
