agent-cerebro 0.1.0__tar.gz

agent_cerebro-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.sqlite3
+.pytest_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+.env
+*.egg

agent_cerebro-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.1 (2026-03-12)
+
+Renamed PyPI package from `agentrecall` to `agentrecall-memory` (PyPI rejected `agentrecall` as too similar to existing `agent-recall`). Python import name (`from agentrecall import ...`) and CLI commands (`agentrecall store/search/...`) are unchanged.
+
+## 0.1.0 (2026-03-11)
+
+Initial release (as agentrecall, renamed from agentmemory).
+
+- Two-tier memory: short-term markdown files + long-term SQLite with OpenAI embeddings
+- CLI: `agentrecall store/search/list/check/init/migrate`
+- Semantic dedup via cosine similarity (threshold >0.92)
+- Keyword fallback when no OpenAI API key
+- Short-term memory file validation (80-line limit, session log pruning)
+- JSONL to SQLite migration tool
+- Agent Skills packaging (`skill/agent-recall/`)
+- Zero required dependencies (SQLite is stdlib)
+- Full pytest suite

agent_cerebro-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ultrathink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_cerebro-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: agent-cerebro
+Version: 0.1.0
+Summary: Persistent two-tier memory for AI agents. Short-term markdown + long-term SQLite with semantic search.
+Project-URL: Homepage, https://github.com/ultrathink-art/agentrecall
+Project-URL: Repository, https://github.com/ultrathink-art/agentrecall
+Project-URL: Issues, https://github.com/ultrathink-art/agentrecall/issues
+Author-email: Ultrathink <ceo@ultrathink.art>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,embeddings,memory,semantic-search,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: openai>=1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: openai>=1.0; extra == 'embeddings'
+Description-Content-Type: text/markdown
+
+# AgentRecall
+
+[![PyPI](https://img.shields.io/pypi/v/agentrecall-memory)](https://pypi.org/project/agentrecall-memory/)
+[![Python](https://img.shields.io/pypi/pyversions/agentrecall-memory)](https://pypi.org/project/agentrecall-memory/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Persistent two-tier memory for AI agents. Battle-tested across 134 sessions with 10 agent roles.
+
+**Short-term** (markdown files, always loaded) + **Long-term** (SQLite + OpenAI embeddings, searched on-demand).
+
+## Install
+
+```bash
+pip install agentrecall-memory
+```
+
+Zero required dependencies. SQLite is Python stdlib.
+
+Optional semantic search:
+```bash
+pip install agentrecall-memory[embeddings]
+export OPENAI_API_KEY="sk-..."
+```
+
+## Quick Start
+
+### CLI
+
+```bash
+# Initialize
+agentrecall init
+
+# Store a memory (auto-dedup via cosine similarity >0.92)
+agentrecall store coder gotchas "kamal app exec spawns new container, use docker exec"
+agentrecall store social exhausted_stories "blue-green deploy order loss" --tags deploy,sqlite
+
+# Search (semantic + keyword fallback)
+agentrecall search coder gotchas "kamal file not found"
+
+# List categories
+agentrecall list coder
+
+# Check health
+agentrecall check --all
+```
+
+### Python API
+
+```python
+from agentrecall import MemoryStore, MemorySearch
+
+# Store
+store = MemoryStore()
+store.store("coder", "gotchas", "kamal spawns new container", tags=["kamal", "docker"])
+
+# Search
+search = MemorySearch()
+results = search.search("coder", "gotchas", "kamal file not found")
+for text in results:
+    print(text)
+
+# List categories
+categories = store.list_categories("coder")
+```
+
+## How It Works
+
+### Two-Tier Design
+
+| Short-term (`memory/<role>.md`) | Long-term (SQLite + embeddings) |
+|---|---|
+| Active learnings, mistakes, feedback | Growing lists (exhausted topics, defect patterns) |
+| Max 80 lines, pruned regularly | Unlimited entries, never pruned |
+| Read in full at session start | Searched on-demand per query |
+
+### Semantic Dedup
+
+Every `store` call embeds the text via OpenAI `text-embedding-3-small` and checks cosine similarity against all existing entries in the same role/category. Similarity > 0.92 blocks the store (raises `DuplicateError`).
+
+Without an API key, falls back to exact text matching.
+
+### Search
+
+1. Embed the query
+2. Compute cosine similarity against all entries with embeddings
+3. Return entries above threshold (0.75), sorted by similarity
+4. If no embedding matches: keyword fallback (>=50% keyword match)
+5. No API key: keyword-only search
+
+### Graceful Degradation
+
+Works fully offline without an OpenAI API key:
+- **Store**: exact text dedup (case-insensitive)
+- **Search**: keyword matching (>=50% of query words must appear)
+
+## Agent Skills
+
+Copy `skill/agent-recall/` into your project's skills directory for use with Claude Code, Codex, Cursor, Copilot, Cline, or Goose.
+
+```bash
+cp -r skill/agent-recall/ .claude/skills/agent-recall/
+```
+
+## Configuration
+
+Environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGENT_RECALL_HOME` | `~/.agentrecall` | Memory storage directory |
+| `OPENAI_API_KEY` | (none) | OpenAI API key for embeddings |
+| `UT_OPENAI_API_KEY` | (none) | Preferred over `OPENAI_API_KEY` |
+
+## CLI Reference
+
+```
+agentrecall store <role> <category> "text" [--tags t1,t2] [--db path]
+agentrecall search <role> <category> "query" [--db path]
+agentrecall list <role> [--db path]
+agentrecall check [--fix] [--long-term] [--all] [--dir path] [--db path]
+agentrecall init [--dir path]
+agentrecall migrate [--dry-run] [--rebuild] [--dir path] [--db path]
+```
+
+Exit codes: `0` = success/found, `1` = not-found/validation-fail, `2` = input error.
+
+## Migration from JSONL
+
+If you have existing JSONL memory files:
+
+```bash
+agentrecall migrate --dir /path/to/memory/
+agentrecall migrate --rebuild  # Re-embed entries missing embeddings
+```
+
+## License
+
+MIT

agent_cerebro-0.1.0/README.md

@@ -0,0 +1,138 @@
+# AgentRecall
+
+[![PyPI](https://img.shields.io/pypi/v/agentrecall-memory)](https://pypi.org/project/agentrecall-memory/)
+[![Python](https://img.shields.io/pypi/pyversions/agentrecall-memory)](https://pypi.org/project/agentrecall-memory/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Persistent two-tier memory for AI agents. Battle-tested across 134 sessions with 10 agent roles.
+
+**Short-term** (markdown files, always loaded) + **Long-term** (SQLite + OpenAI embeddings, searched on-demand).
+
+## Install
+
+```bash
+pip install agentrecall-memory
+```
+
+Zero required dependencies. SQLite is Python stdlib.
+
+Optional semantic search:
+```bash
+pip install agentrecall-memory[embeddings]
+export OPENAI_API_KEY="sk-..."
+```
+
+## Quick Start
+
+### CLI
+
+```bash
+# Initialize
+agentrecall init
+
+# Store a memory (auto-dedup via cosine similarity >0.92)
+agentrecall store coder gotchas "kamal app exec spawns new container, use docker exec"
+agentrecall store social exhausted_stories "blue-green deploy order loss" --tags deploy,sqlite
+
+# Search (semantic + keyword fallback)
+agentrecall search coder gotchas "kamal file not found"
+
+# List categories
+agentrecall list coder
+
+# Check health
+agentrecall check --all
+```
+
+### Python API
+
+```python
+from agentrecall import MemoryStore, MemorySearch
+
+# Store
+store = MemoryStore()
+store.store("coder", "gotchas", "kamal spawns new container", tags=["kamal", "docker"])
+
+# Search
+search = MemorySearch()
+results = search.search("coder", "gotchas", "kamal file not found")
+for text in results:
+    print(text)
+
+# List categories
+categories = store.list_categories("coder")
+```
+
+## How It Works
+
+### Two-Tier Design
+
+| Short-term (`memory/<role>.md`) | Long-term (SQLite + embeddings) |
+|---|---|
+| Active learnings, mistakes, feedback | Growing lists (exhausted topics, defect patterns) |
+| Max 80 lines, pruned regularly | Unlimited entries, never pruned |
+| Read in full at session start | Searched on-demand per query |
+
+### Semantic Dedup
+
+Every `store` call embeds the text via OpenAI `text-embedding-3-small` and checks cosine similarity against all existing entries in the same role/category. Similarity > 0.92 blocks the store (raises `DuplicateError`).
+
+Without an API key, falls back to exact text matching.
+
+### Search
+
+1. Embed the query
+2. Compute cosine similarity against all entries with embeddings
+3. Return entries above threshold (0.75), sorted by similarity
+4. If no embedding matches: keyword fallback (>=50% keyword match)
+5. No API key: keyword-only search
+
+### Graceful Degradation
+
+Works fully offline without an OpenAI API key:
+- **Store**: exact text dedup (case-insensitive)
+- **Search**: keyword matching (>=50% of query words must appear)
+
+## Agent Skills
+
+Copy `skill/agent-recall/` into your project's skills directory for use with Claude Code, Codex, Cursor, Copilot, Cline, or Goose.
+
+```bash
+cp -r skill/agent-recall/ .claude/skills/agent-recall/
+```
+
+## Configuration
+
+Environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGENT_RECALL_HOME` | `~/.agentrecall` | Memory storage directory |
+| `OPENAI_API_KEY` | (none) | OpenAI API key for embeddings |
+| `UT_OPENAI_API_KEY` | (none) | Preferred over `OPENAI_API_KEY` |
+
+## CLI Reference
+
+```
+agentrecall store <role> <category> "text" [--tags t1,t2] [--db path]
+agentrecall search <role> <category> "query" [--db path]
+agentrecall list <role> [--db path]
+agentrecall check [--fix] [--long-term] [--all] [--dir path] [--db path]
+agentrecall init [--dir path]
+agentrecall migrate [--dry-run] [--rebuild] [--dir path] [--db path]
+```
+
+Exit codes: `0` = success/found, `1` = not-found/validation-fail, `2` = input error.
+
+## Migration from JSONL
+
+If you have existing JSONL memory files:
+
+```bash
+agentrecall migrate --dir /path/to/memory/
+agentrecall migrate --rebuild  # Re-embed entries missing embeddings
+```
+
+## License
+
+MIT

agent_cerebro-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-cerebro"
+version = "0.1.0"
+description = "Persistent two-tier memory for AI agents. Short-term markdown + long-term SQLite with semantic search."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Ultrathink", email = "ceo@ultrathink.art" },
+]
+keywords = ["ai-agents", "memory", "embeddings", "sqlite", "semantic-search"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.optional-dependencies]
+embeddings = ["openai>=1.0"]
+all = ["openai>=1.0"]
+dev = ["pytest>=7.0", "pytest-cov"]
+
+[project.urls]
+Homepage = "https://github.com/ultrathink-art/agentrecall"
+Repository = "https://github.com/ultrathink-art/agentrecall"
+Issues = "https://github.com/ultrathink-art/agentrecall/issues"
+
+[project.scripts]
+agentrecall = "agentrecall.cli:main"
+agentmemory = "agentrecall.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentrecall"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

agent_cerebro-0.1.0/skill/agent-recall/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: agent-memory
+description: Persistent two-tier memory for AI agents. Use when storing learnings, searching past work, checking memory health, or following the session start/end memory protocol.
+allowed-tools: Bash(agentrecall *), Bash(python *), Read, Glob
+---
+
+# Agent Recall
+
+Persistent two-tier memory for AI agents. Short-term markdown files (always loaded) + long-term SQLite with semantic search (queried on-demand).
+
+## Setup
+
+```bash
+# Install (zero required deps — SQLite is stdlib)
+pip install agentrecall-memory
+
+# Optional: enable semantic search/dedup
+pip install agentrecall-memory[embeddings]
+export OPENAI_API_KEY="sk-..."
+
+# Initialize memory directory
+agentrecall init
+```
+
+## Quick Reference
+
+### Store a memory
+```bash
+agentrecall store <role> <category> "text" --tags tag1,tag2
+```
+
+### Search memories
+```bash
+agentrecall search <role> <category> "query"
+# Exit 0 = matches found, exit 1 = no matches
+```
+
+### List categories
+```bash
+agentrecall list <role>
+```
+
+### Check health
+```bash
+agentrecall check              # Short-term files
+agentrecall check --long-term  # DB health
+agentrecall check --all        # Both
+agentrecall check --fix        # Auto-prune oversized files
+```
+
+## Protocol
+
+1. **Session start**: Read `memory/<role>.md` — your accumulated knowledge
+2. **Before acting**: `agentrecall search <role> <category> "concept"` to check past work
+3. **After acting**: `agentrecall store <role> <category> "what you learned"`
+4. **Session end**: Update `memory/<role>.md` with mistakes/learnings, run `agentrecall check`
+
+## References
+
+- [Memory Directive](references/memory-directive.md) — full agent protocol
+- [Best Practices](references/best-practices.md) — patterns that work
+- [Categories Guide](references/categories-guide.md) — suggested categories by role
+
+## Scripts
+
+- `scripts/store.py` — programmatic store
+- `scripts/search.py` — programmatic search
+- `scripts/check.py` — programmatic health check
+- `scripts/setup.py` — initialize for a new project

agent_cerebro-0.1.0/skill/agent-recall/references/best-practices.md

@@ -0,0 +1,33 @@
+# Memory Best Practices
+
+## Short-Term (markdown files)
+
+- **Be specific**: "Run `CI=true bin/rails test` after commit" > "Don't forget tests"
+- **Be honest**: Record mistakes — your memory is working notes, not a performance review
+- **Prune actively**: Every update, scan for stale/duplicate entries and remove them
+- **Don't duplicate docs**: If a rule exists in project docs, reference it, don't copy
+- **Newest first**: Append at TOP of each section so the most relevant info is seen first
+
+## Long-Term (SQLite + embeddings)
+
+- **Search before acting**: Always check if you've done similar work before
+- **Store after acting**: Record what you did so future sessions can find it
+- **Use tags**: Tags expand searchability (`--tags deploy,sqlite,orders`)
+- **Let dedup work**: If store rejects as duplicate, that's correct behavior — don't force it
+- **Category naming**: Use `snake_case`. Keep categories focused (10-50 entries ideal)
+
+## Two-Tier Design
+
+| When to use short-term | When to use long-term |
+|---|---|
+| Active lessons you need every session | Growing lists (exhausted topics, known entities) |
+| Recent mistakes to avoid | Historical catalog (past designs, past bugs) |
+| Stakeholder preferences | Reference data searched on-demand |
+
+## Anti-Patterns
+
+- **Append-only logs**: Memory files that only grow → use long-term storage instead
+- **Copying project docs**: Wastes your 80-line budget on info that exists elsewhere
+- **Vague entries**: "Be careful with deploys" teaches nothing
+- **Stale entries**: Bugs that were fixed, tools that changed → delete them
+- **Duplicate lessons**: Same lesson recorded 3+ times means you're not learning from it

agent_cerebro-0.1.0/skill/agent-recall/references/categories-guide.md

@@ -0,0 +1,33 @@
+# Suggested Categories by Role
+
+Any agent can create categories by storing the first entry. Convention: `snake_case`.
+
+| Role | Category | Use |
+|------|----------|-----|
+| social | `exhausted_stories` | Topics/stories already posted |
+| social | `engagement_patterns` | What works on each platform |
+| designer | `rejected_designs` | Concepts rejected and why |
+| designer | `successful_designs` | What sold well and patterns |
+| coder | `fix_attempts` | Past debugging approaches per bug class |
+| coder | `gotchas` | Non-obvious platform/framework traps |
+| qa | `defect_patterns` | Historical defect catalog |
+| operations | `audit_findings` | Systemic issues found and fixes applied |
+| marketing | `published_topics` | Blog/content topics already covered |
+| marketing | `content_performance` | What content drove traffic |
+| security | `vulnerability_patterns` | Recurring vuln types across audits |
+| product | `launch_history` | Products launched and outcomes |
+
+## Creating New Categories
+
+Just store an entry — the category is created implicitly:
+
+```bash
+agentrecall store myagent new_category "first entry in this category"
+```
+
+## Category Size Guidelines
+
+- **< 10 entries**: Category may be too narrow, consider merging
+- **10-50 entries**: Ideal range for focused, searchable memory
+- **50-200 entries**: Still fine — semantic search handles it well
+- **200+ entries**: Consider splitting into subcategories

agent_cerebro-0.1.0/skill/agent-recall/references/memory-directive.md

@@ -0,0 +1,72 @@
+# Agent Memory Protocol
+
+You have persistent memory across sessions. USE IT.
+
+## At Session START
+
+Read your memory file: `memory/<your-role>.md`
+
+Contains accumulated knowledge — mistakes, learnings, feedback, session log. Treat as your personal notebook.
+
+## At Session END
+
+Update your memory file. Add entries to relevant sections. Be specific and actionable.
+
+Run `agentrecall check` to validate size limits. Use `agentrecall check --fix` if over limit.
+
+### What to record
+
+**Mistakes** — what went wrong, correct approach, how to avoid next time.
+
+**Learnings** — non-obvious discoveries, gotchas, workarounds, patterns that work.
+
+**Session Log** — 1-2 lines per session: task ID, what you worked on, outcome.
+
+### Format
+
+Append new entries at TOP of each section (newest first). Date prefix: `[YYYY-MM-DD]`.
+
+### Size limits
+
+- Mistakes: max 20 entries
+- Learnings: max 20 entries
+- Session Log: max 15 entries
+- Total file: max 80 lines
+
+### Pruning rules
+
+- Remove entries duplicated in project instructions
+- Remove stale entries (fixed bugs, removed workarounds)
+- Consolidate duplicate lessons into one entry
+- Use long-term memory (`agentrecall store`) for growing lists
+
+## Long-Term Memory
+
+For data that grows unboundedly (exhausted topics, known patterns, recurring references).
+
+### Search-before-action pattern
+
+```bash
+# Before creating content that might duplicate past work:
+agentrecall search <role> <category> "<concept keywords>"
+# Exit 0 = matches found → skip/choose different topic
+# Exit 1 = no matches → safe to proceed
+
+# After completing work:
+agentrecall store <role> <category> "<what you did>"
+```
+
+## Memory File Template
+
+```markdown
+# {Role} Agent Memory
+
+## Mistakes
+- [2026-03-11] Description of what went wrong and how to avoid it.
+
+## Learnings
+- [2026-03-11] Non-obvious discovery specific to your role.
+
+## Session Log
+- [2026-03-11] Task/summary of what was done.
+```

agent_cerebro-0.1.0/skill/agent-recall/scripts/check.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Check memory health (short-term file limits + DB integrity).
+
+Usage:
+    python check.py [--fix] [--long-term] [--all] [--dir PATH]
+"""
+import sys
+
+from agentrecall.cli import main as cli_main
+
+
+def main():
+    args = ["check"] + sys.argv[1:]
+    try:
+        cli_main(args)
+    except SystemExit as e:
+        sys.exit(e.code)
+
+
+if __name__ == "__main__":
+    main()

agent_cerebro-0.1.0/skill/agent-recall/scripts/search.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Search long-term agent memory.
+
+Usage:
+    python search.py <role> <category> "query"
+    python search.py <role> --list
+"""
+import sys
+
+from agentrecall.longterm.search import run_search, run_list
+
+
+def main():
+    args = sys.argv[1:]
+    if len(args) < 2:
+        print("Usage: python search.py <role> <category> \"query\"", file=sys.stderr)
+        print("       python search.py <role> --list", file=sys.stderr)
+        sys.exit(2)
+
+    role = args[0]
+
+    if args[1] == "--list":
+        sys.exit(run_list(role))
+
+    if len(args) < 3:
+        print("ERROR: query is required", file=sys.stderr)
+        sys.exit(2)
+
+    category = args[1]
+    query = " ".join(args[2:])
+
+    sys.exit(run_search(role, category, query))
+
+
+if __name__ == "__main__":
+    main()