{"id":49557106,"url":"https://github.com/rajkripal/cashew","last_synced_at":"2026-06-28T07:01:25.292Z","repository":{"id":350668202,"uuid":"1175665645","full_name":"rajkripal/cashew","owner":"rajkripal","description":"Persistent memory for AI agents. Extract once, recall forever.","archived":false,"fork":false,"pushed_at":"2026-06-08T03:28:04.000Z","size":24259,"stargazers_count":18,"open_issues_count":9,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-06-08T05:14:24.335Z","etag":null,"topics":["agent-memory","ai-agents","claude-code","graph-memory","knowledge-graph","llm","llm-harness","long-term-memory","memory","personal-knowledge-graph","python","second-brain","semantic-memory","sqlite","vector-search"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rajkripal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-08T02:12:05.000Z","updated_at":"2026-06-08T03:28:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rajkripal/cashew","commit_stats":null,"previous_names":["rajkripal/cashew"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/rajkripal/cashew","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rajkripal%2Fcashew","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rajkripal%2Fcashew/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rajkripal%2Fcashew/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rajkripal%2Fcashew/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rajkripal","download_url":"https://codeload.github.com/rajkripal/cashew/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rajkripal%2Fcashew/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34880189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-agents","claude-code","graph-memory","knowledge-graph","llm","llm-harness","long-term-memory","memory","personal-knowledge-graph","python","second-brain","semantic-memory","sqlite","vector-search"],"created_at":"2026-05-03T05:02:29.295Z","updated_at":"2026-06-28T07:01:25.287Z","avatar_url":"https://github.com/rajkripal.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cashew 🥜\n\n**Persistent thought-graph memory for AI agents.**\n\n[![PyPI](https://img.shields.io/pypi/v/cashew-brain)](https://pypi.org/project/cashew-brain/)\n[![Downloads](https://static.pepy.tech/badge/cashew-brain)](https://pepy.tech/project/cashew-brain)\n[![Downloads/month](https://static.pepy.tech/badge/cashew-brain/month)](https://pepy.tech/project/cashew-brain)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nThe name comes from asking \"do cats eat cashews?\", a question I asked my aunt as a 10-year-old kid in India, because the cashews were left open in the kitchen and I knew stray cats sneak into homes to eat food. My family still brings it up every time I visit. I never stopped asking questions. This system doesn't either: autonomous think cycles find connections you didn't know existed.\n\n📝 **Blog post:** [I Built My AI a Brain and It Started Thinking for Itself](https://open.substack.com/pub/rajkripaldanday/p/i-built-my-ai-a-brain-and-it-started)\n\n## Architecture\n\n![Cashew Architecture](docs/architecture-diagram.png)\n\n## What It Does\n\n- **Remembers across sessions.** Decisions, patterns, relationships, and project context survive compaction and restart. Your agent picks up where it left off.\n- **Learns autonomously.** Think cycles find cross-domain connections without prompting. A pattern in your work habits connects to a pattern in your communication style, and the brain surfaces it.\n- **Stays fast at scale.** sqlite-vec for O(log N) retrieval, recursive BFS graph walk, constant context cost regardless of graph size. 3,000 nodes costs the same as 300.\n\n## What If Forgetting Is the Intelligence?\n\nCashew doesn't hoard everything. Organic decay means low-value knowledge fades naturally while important patterns strengthen through use. No manual curation needed: the graph self-organizes through cross-linking and natural selection. See [PHILOSOPHY.md](PHILOSOPHY.md) for the full manifesto.\n\n## Quick Start\n\n```bash\npip install cashew-brain\ncashew init\ncashew context --hints \"test\"\n```\n\nThat's it. Your brain is empty but ready. Start extracting knowledge:\n\n```bash\necho \"I prefer TypeScript over JavaScript for complex projects\" | cashew extract --input -\n```\n\nQuery it back:\n\n```bash\ncashew context --hints \"programming language preferences\"\n```\n\n## Integration\n\n### Claude Code\n\nCopy the skill into your personal skills directory:\n\n```bash\n# From the cashew repo\ncp -r skills/claude-code/ ~/.claude/skills/cashew/\n```\n\nThis gives you the `/cashew` slash command and automatic context loading. Claude Code will query your brain before answering substantive questions and extract knowledge during conversations.\n\nOr if you cloned the repo, just open it in Claude Code. The `.claude/skills/cashew/` directory auto-discovers.\n\n### OpenClaw\n\nInstall as an OpenClaw skill for full automation. Cron jobs handle extraction, think cycles, and dashboard deployment without manual intervention. See `skills/openclaw/SKILL.md` for setup instructions.\n\n### Hermes Agent\n\nUse cashew as the memory provider for [NousResearch's Hermes Agent](https://hermes-agent.nousresearch.com/) via [hermes-cashew](https://github.com/magnus919/hermes-cashew), a plugin maintained by [Magnus Hedemark](https://github.com/magnus919):\n\n```bash\nhermes plugins install magnus919/hermes-cashew\n```\n\nThe plugin exposes `cashew_query` and `cashew_extract` as agent-callable tools, auto-injects relevant context at session start, and works against a local cashew brain with no extra services. See the [hermes-cashew README](https://github.com/magnus919/hermes-cashew) for configuration and tuning notes.\n\n### Ingest Sources\n\nCashew ships with built-in extractors for common knowledge sources. Each one handles checkpointing, incremental updates, and deduplication automatically.\n\n**Obsidian vault:**\n\n```bash\ncashew ingest obsidian /path/to/vault\n```\n\nParses YAML frontmatter (tags, aliases, dates), follows `[[wikilinks]]` to create edges between related notes, respects `.obsidianignore`, and auto-detects domains from your folder structure.\n\n**OpenClaw session logs:**\n\n```bash\ncashew ingest sessions /path/to/sessions/\n```\n\nExtracts knowledge from conversation history. Tracks how far into each session file it's read, so growing sessions get incrementally processed. Filters out tool calls and system messages.\n\n**Markdown directory:**\n\n```bash\ncashew ingest markdown /path/to/notes/\n```\n\nGeneral purpose extractor for any directory of `.md` files. Respects `.cashewignore` for excluding files.\n\n**Claude.ai conversation archive:**\n\n```bash\ncashew ingest claude_archive /path/to/claude/export/\n```\n\nExtracts knowledge from `conversations.json` — the Claude.ai data export format. Walks content blocks to strip tool calls and results, keeping only human/assistant text. Supports incremental processing via conversation UUIDs, so re-running on the same directory only processes new or updated conversations. Also accepts a direct path to `conversations.json` for convenience.\n\n**Options:**\n\n```bash\ncashew ingest --list          # Show available extractors\ncashew ingest obsidian /path --no-llm  # Skip LLM, use paragraph splitting fallback\n```\n\nAll extractors use LLM-based extraction by default for richer, typed knowledge (decisions, insights, facts). Use `--no-llm` for offline or token-free ingestion.\n\n### Python API\n\n```python\nfrom core.context import ContextRetriever\nfrom core.embeddings import load_embeddings\n\n# Query context\nembeddings = load_embeddings(\"path/to/graph.db\")\nretriever = ContextRetriever(\"path/to/graph.db\", embeddings)\ncontext = retriever.generate_context(hints=[\"work\", \"projects\"])\n```\n\n## Architecture\n\n- **Single SQLite file.** No external servers, no separate indexes. Your entire brain is one portable file.\n- **Local embeddings.** all-MiniLM-L6-v2 (384 dims). Downloads ~500MB on first run, then runs locally forever. No API calls for retrieval.\n- **LLM for intelligence.** Extraction and think cycles need an LLM (Claude, GPT, etc). Retrieval and storage don't. Bring your own via `model_fn` parameter or API key.\n- **Retrieval.** sqlite-vec seeds (O(log N) nearest neighbor) → recursive BFS graph walk (seeds=5, picks_per_hop=3, max_depth=3). The graph's organic connectivity provides implicit hierarchy, so no synthetic summary nodes are needed.\n- **Organic decay.** Nodes that aren't accessed lose fitness over time. Low-fitness nodes get marked decayed and excluded from retrieval.\n\n## CLI Reference\n\n| Command | Purpose |\n|---------|---------|\n| `cashew init` | Initialize a new brain |\n| `cashew context --hints \"...\"` | Retrieve relevant context |\n| `cashew extract --input file.md` | Extract knowledge from text |\n| `cashew ingest obsidian /path` | Ingest an Obsidian vault |\n| `cashew ingest sessions /path` | Ingest OpenClaw session logs |\n| `cashew ingest markdown /path` | Ingest a directory of markdown files |\n| `cashew ingest claude_archive /path` | Ingest a claude.ai conversation archive |\n| `cashew think` | Run a think cycle |\n| `cashew sleep` | Full sleep cycle (consolidation) |\n| `cashew stats` | Graph statistics |\n| `cashew dashboard` | Launch the live dashboard (graph + BFS search visualization) |\n\n### Dashboard\n\n```bash\ncashew dashboard --db data/graph.db --port 8765\n# then open http://127.0.0.1:8765\n```\n\nA minimalist browser UI over the brain. The full graph renders as a canvas force layout colored by node type. The search box traces a live recursive-BFS walk: seeds arrive first, then each hop lights up in order with hop-colored edges and rings. Works on mobile (bottom sheet, drag-to-resize). Pass `--host 0.0.0.0` to expose on the LAN. Auto-trigger a search via `?q=...` in the URL.\n\n## Warm Daemon\n\nEvery CLI invocation normally loads the sentence-transformer model from scratch (~2s cold start). For a responsive query loop, run the warm daemon once and every call routes through it automatically, with no code changes in consumers.\n\n```bash\n# Foreground (development)\ncashew serve\n\n# Persistent (macOS)\ncp packaging/com.cashew.daemon.plist ~/Library/LaunchAgents/\n# edit CASHEW_PATH in the plist to match your clone, then:\nlaunchctl load ~/Library/LaunchAgents/com.cashew.daemon.plist\n```\n\nThe daemon listens on `~/.cashew/daemon.sock`. A content-hash embedding cache at `~/.cashew/embedding_cache.db` makes repeat embeds free, keyed by `(model_version, sha256(text))`. Deterministic by construction, so no invalidation logic is needed beyond model swaps.\n\nEvery entry point (`context`, `extract`, `think`, sleep cycles) checks the cache first, then the daemon, then falls back to in-process embedding if the daemon is down. Clients never need to know which path served them.\n\n## Requirements\n\n- Python 3.10+\n- ~2GB RAM (for embedding model)\n- ~500MB disk (embedding model, downloaded on first use)\n- An LLM API key for extraction and think cycles (optional for retrieval-only use)\n\n## Philosophy\n\nCashew ships with a philosophy document that defines how a brain-equipped agent should operate. It covers brain sovereignty, evidence over defaults, the sponge principle, cross-domain vision, and why divergence between instances is the whole point.\n\nRead it: [PHILOSOPHY.md](PHILOSOPHY.md)\n\n## Development\n\n```bash\ngit clone https://github.com/rajkripal/cashew.git\ncd cashew\npip install -e \".[dev]\"\npytest\n```\n\nSee [CLAUDE.md](CLAUDE.md) for the developer guide: architecture, schema, conventions, and engineering philosophy.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n---\n\nBuilt by [rajkripal](https://github.com/rajkripal).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frajkripal%2Fcashew","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frajkripal%2Fcashew","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frajkripal%2Fcashew/lists"}