{"id":47170610,"url":"https://github.com/keepnotes-ai/keep","last_synced_at":"2026-05-11T22:06:00.041Z","repository":{"id":335564434,"uuid":"1146270506","full_name":"keepnotes-ai/keep","owner":"keepnotes-ai","description":"Reflective memory for AI agents","archived":false,"fork":false,"pushed_at":"2026-04-08T00:25:43.000Z","size":6748,"stargazers_count":26,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-08T00:28:48.991Z","etag":null,"topics":["agent","ai","ai-memory","memory"],"latest_commit_sha":null,"homepage":"https://docs.keepnotes.ai/guides/quickstart/","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/keepnotes-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-30T21:07:16.000Z","updated_at":"2026-04-08T00:25:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/keepnotes-ai/keep","commit_stats":null,"previous_names":["hughpyle/assocmem","keepnotes-ai/keep"],"tags_count":340,"template":false,"template_full_name":null,"purl":"pkg:github/keepnotes-ai/keep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keepnotes-ai%2Fkeep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keepnotes-ai%2Fkeep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keepnotes-ai%2Fkeep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keepnotes-ai%2Fkeep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keepnotes-ai","download_url":"https://codeload.github.com/keepnotes-ai/keep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keepnotes-ai%2Fkeep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31778580,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T00:11:49.126Z","status":"online","status_checked_at":"2026-04-14T02:00:06.344Z","response_time":153,"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","ai","ai-memory","memory"],"created_at":"2026-03-13T05:01:24.089Z","updated_at":"2026-04-14T02:00:59.559Z","avatar_url":"https://github.com/keepnotes-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# keep\n\nAgent memory that pays attention.  The foundation of skillful action.\n\nIt includes [skill instructions](SKILL.md) for reflective practice, and a powerful semantic memory system with [command-line](docs/QUICKSTART.md) and [MCP](docs/KEEP-MCP.md) interfaces. Fully local, or use API keys for model providers, or [cloud-hosted](https://keepnotes.ai) for multi-agent use.\n\n```bash\nuv tool install keep-skill       # or: pip install keep-skill\nkeep                              # interactive first-run setup (providers + agent hooks)\n\n# Index content\nkeep put https://inguz.substack.com/p/keep -t topic=practice\nkeep put \"Rate limit is 100 req/min\" -t topic=api\n\n# Index a codebase — recursive, with daemon-driven watch for changes\nkeep put ./my-project/ -r --watch\n\n# Search by meaning\nkeep find \"what's the rate limit?\"\n\n# Track what you're working on\nkeep now \"Debugging auth flow\"\n\n# Instructions for reflection\nkeep prompt reflect\n```\n\n---\n\n## What It Does\n\nStore anything — notes, files, URLs — and `keep` summarizes, embeds, and tags each note. You search by meaning, by keyword, and by graph traversal.\n\nContent goes in as conversation, text, PDF, HTML, Office documents, audio, or images; what comes back is a summary with tags and semantic neighbors. Audio files auto-extract metadata (artist, album, year); image files auto-extract EXIF (camera, date, dimensions). Optional vision/transcription enrichment runs when a media provider is configured, and scanned PDFs and images get background OCR when an OCR provider is available.\n\nFull content is only stored if it's short (~3kB, configurable) - everything else gets summarized. Chunked analysis and summarization produces a focused searchable index that references original files or URLs without filling your disk with duplicated data.\n\nThis is more than a vector store: selected tags become **edges**. A tag becomes an edge when its tagdoc declares an `_inverse` — for example, `.tag/speaker` declares `_inverse: said`, so `speaker: Deborah` on a note makes `keep get Deborah` show every note where Deborah spoke. Ordinary tags stay as labels; you opt into navigability per tag key. Bundled edges include `speaker`, `author`, `references`, `cites`, `from`/`to`/`cc`, and `git_commit`; you can define your own. When you retrieve any note, keep follows its edges and fires standing queries (`.meta/*`) — surfacing open commitments, past learnings, related files, commit history. The right things appear at the right time. See [docs/EDGE-TAGS.md](docs/EDGE-TAGS.md).\n\n- **Summarize, embed, tag** — URLs, files, and text are summarized and indexed on ingest\n- **Contextual feedback** — Open commitments and past learnings surface automatically\n- **Search** — Semantic similarity, BM25 full-text, and ranked graph traversal; scope to a folder or project\n- **Tag organization** — Speech acts, status, project, topic, type — structured and queryable\n- **Deep search** — Follow edges and tags from results to discover related notes across the graph\n- **Edge tags** — Turn tags into navigable relationships with automatic inverse links\n- **Git changelog** — Commits indexed as searchable notes with edges to touched files\n- **Parts** — `analyze` decomposes documents into searchable sections, each with its own embedding and tags\n- **Strings** — Every note is a string of versions; reorganize history by meaning with `keep move`\n- **Watches** — Daemon-driven directory and file monitoring; re-indexes on change\n- **Works offline** — Local models (MLX, Ollama, etc.), or API providers (Voyage, OpenAI, Gemini, Anthropic, Mistral)\n\n\u003e **[keepnotes.ai](https://keepnotes.ai)** — Hosted service. No local setup, no API keys to manage. Same SDK, managed infrastructure.\n\n### The Practice\n\nkeep is designed as a skill for AI agents — a practice, not just a tool. The [skill instructions](SKILL.md) teach agents to reflect before, during, and after action: check intentions, recognize commitments, capture learnings, notice breakdowns. `keep prompt reflect` guides a structured reflection ([details](docs/KEEP-PROMPT.md)); `keep now` tracks current intentions and surfaces what's relevant.\n\nThis works because the tool and the skill reinforce each other. The tool stores and retrieves; the skill says *when* and *why*. An agent that uses both develops *skillful action* across sessions — not just recall, but looking before acting, and a deep review of outcomes afterwards.\n\n\u003e Why build memory for AI agents? What does \"reflective practice\" mean here? **[Read our blog for the back-story →](https://keepnotes.ai/blog/)**\n\n### Integration\n\nRun `keep` (or `keep config --setup`) and the interactive wizard offers to install hooks for the coding-tool integrations it detects on your system. The other rows below have their own setup commands.\n\n| Tool | How to install |\n|------|-------------|\n| **[Hermes Agent](docs/HERMES-INTEGRATION.md)** | `curl -sSL https://keepnotes.ai/scripts/install-hermes.sh \\| bash` — installs plugin and runs setup. Fully integrated, with [additional skills](https://github.com/keepnotes-ai/hermes-skills) available. |\n| **[OpenClaw](docs/OPENCLAW-INTEGRATION.md)** | `openclaw plugins install clawhub:keep` (or `-l $(keep config openclaw-plugin)` from a local checkout). After that, `keep config --setup` keeps the plugin upgraded. Context engine plugin — full memory assembly, session archival, reflection triggers. |\n| **Claude Desktop** | `keep config --setup`, then `keep config mcpb` to generate and open the .mcpb bundle ([details](docs/CLAUDE-DESKTOP.md)) |\n| **Claude Code** | `/plugin marketplace add https://github.com/keepnotes-ai/keep.git` then `/plugin install keep@keepnotes-ai` |\n| **VS Code Copilot** | `export KEEP_STORE_PATH=...` then `code --add-mcp \"{\\\"name\\\":\\\"keep\\\",\\\"command\\\":\\\"keep\\\",\\\"args\\\":[\\\"--store\\\",\\\"$KEEP_STORE_PATH\\\",\\\"mcp\\\"]}\"` |\n| **GitHub Copilot CLI** | Auto-installed by `keep config --setup` when `~/.copilot/` is present. |\n| **Kiro** | `export KEEP_STORE_PATH=...` then `kiro-cli mcp add --name keep --scope global -- keep --store \"$KEEP_STORE_PATH\" mcp` |\n| **OpenAI Codex** | `export KEEP_STORE_PATH=...` then `codex mcp add keep -- keep --store \"$KEEP_STORE_PATH\" mcp` |\n| **LangChain** | [LangGraph BaseStore](docs/LANGCHAIN-INTEGRATION.md), retriever, tools, and middleware |\n| **Any MCP client** | [Stdio server](docs/KEEP-MCP.md) with 3 tools (`keep_flow`, `keep_prompt`, `keep_help`) |\n\nAfter install, just tell your agent: *Please read all the keep_help documentation, and then use keep_prompt(name=\"reflect\") to save some notes about what you learn.*\n\nManual MCP setup should treat `KEEP_STORE_PATH` as the source of truth and bake\nthat value into the launched `keep` command with `--store`; many MCP hosts do\nnot inherit arbitrary shell environment variables into stdio server processes.\n\n---\n\n## Installation\n\n**Python 3.11–3.13.** Use [uv](https://docs.astral.sh/uv/) (recommended) or pip:\n\n```bash\nuv tool install keep-skill        # or: pip install keep-skill\nkeep                               # interactive first-run setup\n```\n\nThe first run launches an interactive wizard: it picks up any API keys you have in the environment, detects [Ollama](https://ollama.com/) if it's running locally, lets you pick embedding and summarization providers, and offers to install hooks for any agent tools it finds. Re-run anytime with `keep config --setup`.\n\n**Skip the wizard** by setting one of:\n\n```bash\nexport KEEPNOTES_API_KEY=kn_...    # Hosted at https://keepnotes.ai — no local setup needed\nexport OPENAI_API_KEY=...          # Or GEMINI_API_KEY, OPENROUTER_API_KEY — each does both embeddings + summarization\nexport VOYAGE_API_KEY=...          # Or MISTRAL_API_KEY — embeddings only; pair with ANTHROPIC_API_KEY etc. for summarization\nexport GOOGLE_CLOUD_PROJECT=...    # Vertex AI via Workload Identity / ADC\n```\n\nLocal option without API keys: install Ollama (auto-detected), or on macOS Apple Silicon `uv tool install 'keep-skill[local]'` for MLX models.\n\nOr use a local OpenAI-API server (llama-server, vLLM, LM Studio, LocalAI) by setting `[embedding] name = \"openai\"` with `base_url = \"http://localhost:8801/v1\"` in `keep.toml` — see [docs/KEEP-CONFIG.md](docs/KEEP-CONFIG.md).\n\n**LangChain/LangGraph** integration: `pip install keep-skill[langchain]` or `pip install langchain-keep`.\n\nSee [docs/QUICKSTART.md](docs/QUICKSTART.md) and [docs/KEEP-CONFIG.md](docs/KEEP-CONFIG.md) for the full provider matrix and configuration options.\n\n---\n\n## Quick Start\n\n```bash\n# Index URLs, files, and notes (store auto-initializes on first use)\nkeep put https://example.com/api-docs -t topic=api\nkeep put \"Token refresh needs clock sync\" -t topic=auth\n\n# Index a codebase — recursive, with auto-watch for changes\nkeep put ./my-project/ -r --watch\n# git: 2 repo(s) queued for changelog ingest\n\n# Search\nkeep find \"authentication flow\" --limit 5\nkeep find \"auth\" --deep                # Follow edges to discover related notes\nkeep find \"auth\" --scope 'file:///Users/me/project/*'  # Scoped to a folder\n\n# Retrieve\nkeep get file:///path/to/doc.md\nkeep get ID --history                  # All versions\nkeep get ID --parts                    # Analyzed sections\n\n# Tags\nkeep list --tag project=myapp          # Find by tag\nkeep list 'git://github.com/org/repo@*'  # All git tags/releases\n\n# Current intentions\nkeep now                               # Show what you're working on\nkeep now \"Fixing login bug\"            # Update intentions\n```\n\n### Python API\n\n```python\nfrom keep import Keeper\n\nkp = Keeper()\n\n# Index\nkp.put(uri=\"file:///path/to/doc.md\", tags={\"project\": \"myapp\"})\nkp.put(\"Rate limit is 100 req/min\", tags={\"topic\": \"api\"})\n\n# Search\nresults = kp.find(\"rate limit\", limit=5)\nfor r in results:\n    print(f\"[{r.score:.2f}] {r.summary}\")\n\n# Version history\nprev = kp.get_version(\"doc:1\", offset=1)\nversions = kp.list_versions(\"doc:1\")\n```\n\nSee [docs/QUICKSTART.md](docs/QUICKSTART.md) for configuration and more examples.\n\n---\n\n## Documentation\n\nFull docs at **[docs.keepnotes.ai](https://docs.keepnotes.ai)** — or browse locally:\n\n- **[docs/QUICKSTART.md](docs/QUICKSTART.md)** — Setup, configuration, first steps\n- **[docs/REFERENCE.md](docs/REFERENCE.md)** — Quick reference index\n- **[docs/KEEP-PUT.md](docs/KEEP-PUT.md)** — Indexing: files, directories, URLs, git changelog, watches\n- **[docs/KEEP-FIND.md](docs/KEEP-FIND.md)** — Semantic search, deep search, scoped search\n- **[docs/TAGGING.md](docs/TAGGING.md)** — Tags, speech acts, project/topic organization\n- **[docs/PROMPTS.md](docs/PROMPTS.md)** — Prompts for summarization, analysis, and agent workflows\n- **[docs/OPENCLAW-INTEGRATION.md](docs/OPENCLAW-INTEGRATION.md)** — OpenClaw context engine plugin\n- **[docs/KEEP-MCP.md](docs/KEEP-MCP.md)** — MCP server for AI agent integration\n- **[docs/AGENT-GUIDE.md](docs/AGENT-GUIDE.md)** — Working session patterns\n- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — How it works under the hood\n- **[SKILL.md](SKILL.md)** — The reflective practice (for AI agents)\n\n---\n\n## License\n\nMIT\n\n---\n\n## Contributing\n\nPublished on [PyPI as `keep-skill`](https://pypi.org/project/keep-skill/).\n\nIssues and PRs welcome:\n- Provider implementations\n- Performance improvements\n- Documentation clarity\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeepnotes-ai%2Fkeep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeepnotes-ai%2Fkeep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeepnotes-ai%2Fkeep/lists"}