{"id":44513651,"url":"https://github.com/steadman-labs/quaid","last_synced_at":"2026-03-01T06:01:08.867Z","repository":{"id":338164026,"uuid":"1156757411","full_name":"Steadman-Labs/quaid","owner":"Steadman-Labs","description":"Memory and project management plugin for OpenClaw","archived":false,"fork":false,"pushed_at":"2026-02-18T14:44:42.000Z","size":2552,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-18T17:54:36.531Z","etag":null,"topics":["ai","embeddings","llm","memory","openclaw","rag","sqlite"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Steadman-Labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T02:37:11.000Z","updated_at":"2026-02-18T14:46:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"fa7c9720-e5b8-45b0-aafd-96a5aa6364b6","html_url":"https://github.com/Steadman-Labs/quaid","commit_stats":null,"previous_names":["steadman-labs/quaid"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Steadman-Labs/quaid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steadman-Labs%2Fquaid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steadman-Labs%2Fquaid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steadman-Labs%2Fquaid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steadman-Labs%2Fquaid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Steadman-Labs","download_url":"https://codeload.github.com/Steadman-Labs/quaid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steadman-Labs%2Fquaid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29621882,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T13:04:20.082Z","status":"ssl_error","status_checked_at":"2026-02-19T13:03:33.775Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai","embeddings","llm","memory","openclaw","rag","sqlite"],"created_at":"2026-02-13T16:16:26.513Z","updated_at":"2026-02-23T10:22:13.368Z","avatar_url":"https://github.com/Steadman-Labs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/quaid-logo.png\" alt=\"Quaid\" width=\"500\"\u003e\n  \u003cbr\u003e\n  \u003cem\u003e\"If I am not me, then who the hell am I?\"\u003c/em\u003e\n\u003c/p\u003e\n\n### A Knowledge Layer for Agentic Systems\n\n\u003e **Early alpha** — launched February 2026, active daily development.\n\nMost agents still treat long-term context as replay: re-inject old chat and hope retrieval lands. Quaid is not another memory plugin; it is an **active knowledge layer**. It continuously captures, structures, and maintains knowledge, then serves only what matters at query time. Result: 89% of full-context accuracy using ~8x fewer tokens.\n\nEvery session starts ready to work. Project docs, architecture decisions, tool guidance, and codebase context are tracked and kept current automatically. Through dual snippet/journal learning, the layer evolves with use: it doesn't just retain facts, it builds durable understanding of users, workflows, and projects over time.\n\n**What it remembers:**\n- **Facts** — names, relationships, preferences, decisions, life events\n- **Projects** — documentation, architecture, tools, tracked from git changes\n- **Personality** — who your user is, who the agent is, how they interact — evolving over time\n\n**What it does with them:**\n- Extracts memories from conversations automatically\n- Retrieves the right ones at the right time (hybrid search + LLM reranking)\n- Runs a nightly janitor that reviews, deduplicates, resolves contradictions, and decays stale memories\n- Keeps project docs and personality files current without manual maintenance\n\nQuaid is an agentic-system independent knowledge layer by design, with adapters handling host-specific runtime details. Today, the most mature integration is [OpenClaw](https://github.com/openclaw/openclaw); standalone MCP/CLI flows are supported, and MCP client coverage outside OpenClaw should currently be treated as experimental.\n\n**Interface surfaces:**\n- **OpenClaw adapter** — lifecycle hooks + tool integration (most mature path)\n- **MCP server** — host-agnostic tool surface for any MCP-capable client *(experimental coverage outside OpenClaw)*\n- **CLI** — direct operational control for extraction, recall, janitor, docs, and events\n\nRuntime event capabilities are discoverable (`memory_event_capabilities`, `quaid event capabilities`) so orchestration can adapt to host/runtime support instead of assuming fixed behavior.\n\n---\n\n## Install\n\nThe guided installer sets up Quaid with knowledge capture, janitor scheduling, and host integration.\n\n**Mac / Linux:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/steadman-labs/quaid/main/install.sh | bash\n```\n\n**Windows:**\n```powershell\nirm https://raw.githubusercontent.com/steadman-labs/quaid/main/install.ps1 | iex\n```\n\n**Manual (all platforms):**\n```bash\ngit clone https://github.com/steadman-labs/quaid.git\ncd quaid \u0026\u0026 node setup-quaid.mjs\n```\n\n---\n\n## Benchmarks\n\n## How Quaid Is Different\n\n- **Local-first by default:** memory graph, embeddings, and maintenance run on your machine.\n- **Three knowledge areas:** facts, core personality, and project knowledge are treated differently instead of flattened into one store.\n- **Lifecycle maintenance, not just storage:** nightly janitor pipeline continuously reviews, deduplicates, resolves contradictions, and decays stale knowledge.\n- **Dual learning system:** fast snippets + slower journal distillation for long-term synthesis.\n- **OpenClaw-first, system-agnostic design:** deepest integration today is OpenClaw, but the architecture is built around adapter contracts.\n\nEvaluated on the [LoCoMo benchmark](https://github.com/snap-research/locomo) (ACL 2024) using Mem0's exact evaluation methodology — same judge model (GPT-4o-mini), same prompt, same scoring. 10 long conversations, 1,540 scored question-answer pairs testing knowledge capture quality, temporal reasoning, and multi-hop recall.\n\n| System | Accuracy | Answer Model |\n|--------|----------|-------------|\n| **Quaid** | **70.3%** | Haiku |\n| Mem0 (graphRAG) | 68.9% | GPT-4o-mini |\n| Mem0 | 66.9% | GPT-4o-mini |\n| Zep | 66.0% | GPT-4o-mini |\n| LangMem | 58.1% | GPT-4o-mini |\n| OpenAI Memory | 52.9% | GPT-4o-mini |\n\nWith Opus answering (recommended production config): **75.0%**\n\n**Token efficiency:** Quaid retrieves about 10 relevant facts per query, averaging **about 200 tokens** of injected memory context. That's it. No raw transcript chunks, no bloated session logs. Embeddings are fully local (Ollama), so vector search has zero API cost. The only per-query API spend is a fast-reasoning LLM reranker call (about $0.01).\n\n\u003e Mem0, Zep, LangMem, and OpenAI numbers are from their [April 2025 paper](https://arxiv.org/abs/2504.01094).\n\u003e Full-context baselines: Haiku 79.6%, Opus 86.6%.\n\u003e\n\u003e Full methodology and per-category breakdowns: [docs/BENCHMARKS.md](docs/BENCHMARKS.md)\n\nLoCoMo evaluates personal fact recall — one of Quaid's three memory areas. The benchmark doesn't measure project documentation tracking, auto-doc refresh, or workspace context management, which have no equivalent in the other systems tested.\n\n---\n\n## How It Works\n\nQuaid organizes knowledge into three areas, each with different retrieval behavior, and maintains them with four systems.\n\n### Three knowledge areas\n\n**Fact knowledge** — User facts, relationships, preferences, experiences. Retrieved via hybrid search (vector + keyword + graph traversal) with LLM reranking — only the most relevant facts are injected per query.\n\n**Core personality** — Deeper understanding of the user, the agent's own identity, and the world around it. Loaded as full context on every conversation — always available, always current.\n\n**Project knowledge** — Documentation, project structure, tool APIs. Available via RAG search — full documents loaded when relevant. Projects aren't just code — this covers any sustained effort: a codebase, an essay, a YouTube channel, a home renovation.\n\n### Four systems\n\n**Knowledge Capture \u0026 Recall** — Conversations are distilled into structured facts, relationships, and preferences stored in a SQLite graph database. Retrieval uses hybrid search, LLM reranking, and intent-aware fusion to find the right knowledge at the right time.\n\n**Journal \u0026 Personality** — A dual learning system. Fast-path *snippets* capture small observations and fold them into core personality files. Slow-path *journal entries* accumulate over time and get distilled into deeper insights — the kind of perceived, inferred understanding that makes an agent feel like it actually knows you.\n\n**Projects \u0026 Docs** — Auto-discovers project structure, tracks documentation, and keeps docs current from git changes. Comprehensive docs beat partial docs — partial or outdated docs mislead the LLM. This also keeps system-level knowledge out of the memory graph, where it would pollute fact retrieval.\n\n**Workspace Maintenance** — A nightly janitor pipeline that batches the day's work into a window where deep-reasoning LLMs can curate knowledge economically. Reviews, deduplicates, resolves contradictions, decays stale facts, and monitors documentation health in bulk.\n\n---\n\n## Design Philosophy: LLM-First\n\nAlmost every decision in Quaid is algorithm-assisted but ultimately arbitrated by an LLM appropriate for the task. The system splits work between a **deep-reasoning LLM** (fact review, contradiction resolution, journal distillation) and a **fast-reasoning LLM** (reranking, dedup verification, query expansion) to balance quality against cost and speed. The fast-reasoning model isn't just cheaper — it's fast. Memory recall needs to feel instant, not take three seconds waiting on a premium model to rerank results.\n\nBecause the system leans heavily on LLM reasoning, Quaid naturally scales with AI models — as reasoning capabilities improve, every decision in the pipeline gets better without code changes.\n\n---\n\n## Cost\n\nQuaid is free and open source. These are typical API costs you pay directly to your configured LLM provider (provider/model dependent):\n\n| Component | API Cost |\n|-----------|----------|\n| Fact extraction | $0.05–0.20 per compaction (deep-reasoning LLM) |\n| Knowledge recall | $0.01 per query (fast-reasoning LLM reranker) |\n| Nightly janitor | $1–5 per run |\n| Embeddings | Free (Ollama, runs locally) |\n| **Typical monthly total** | **$5–15 for active use** |\n\nWe haven't yet fully evaluated the cost savings Quaid provides by reducing context window usage and improving retrieval precision, but they are estimated to be substantial. Quantifying this is a work in progress.\n\n---\n\n## Requirements\n\n- Python 3.10+\n- SQLite 3.35+\n- [Ollama](https://ollama.ai) (for local embeddings)\n- For OpenClaw integration: [OpenClaw](https://github.com/openclaw/openclaw) gateway\n- Gateway-managed provider auth (OAuth/API key) when running inside an agentic host like OpenClaw\n- Optional standalone auth/config when running via MCP/CLI outside a host gateway\n\n---\n\n## Early Alpha\n\nQuaid is in early alpha. LLM routing is adapter- and config-driven (`deep_reasoning` / `fast_reasoning`), with provider/model resolution handled through the gateway provider layer. Ollama remains the default embeddings path.\n\nKnown limitations for **v0.2.0-alpha**:\n- Parallel-session targeting for `/new` and `/reset` extraction still has edge cases.\n- Multi-user workloads are partially supported but not fully hardened under heavy concurrency.\n- Windows support exists but has less operational coverage than macOS/Linux *(experimental)*.\n- OpenClaw is currently the most mature host integration path; broader host coverage is still in progress *(experimental outside OpenClaw)*.\n\nThe system is backed by over 1,100 unit tests (Python + TypeScript), 15 automated installer scenarios covering fresh installs, dirty upgrades, data preservation, migration, missing dependencies, and provider combinations, plus benchmark evaluation against [LoCoMo](docs/BENCHMARKS.md) and [LongMemEval](https://github.com/xiaowu0162/LongMemEval).\n\nGitHub Actions CI runs automated checks on pushes/PRs (runtime pair sync, docs/release consistency, TypeScript integration, and isolated Python unit suites).\n\nWe're actively testing and refining the system against benchmarks and welcome collaboration. If you're interested in contributing, testing, or just have ideas — open an issue or reach out.\n\n---\n\n## Learn More\n\n- [Architecture Guide](docs/ARCHITECTURE.md) — How Quaid works under the hood\n- [Vision](VISION.md) — Project scope, guardrails, and non-goals\n- [AI Agent Reference](docs/AI-REFERENCE.md) — Complete system index for AI assistants\n- [Interface Contract](docs/INTERFACES.md) — MCP/CLI/adapter capability model and event contract\n- [Benchmark Results](docs/BENCHMARKS.md) — Full LoCoMo evaluation with per-category breakdowns\n- [Notification Strategy](docs/NOTIFICATIONS.md) — Feature-level notification model and delayed request flow\n- [Provider Modes](docs/PROVIDER-MODES.md) — Provider routing and cost-safety guidance\n- [Release Workflow](docs/RELEASE.md) — Pre-push checks and ownership guard\n- [Maintainer Lifecycle](docs/MAINTAINER-LIFECYCLE.md) — Safe branch/release model for post-user operation\n- [Contributing](CONTRIBUTING.md) — PR expectations, validation, and AI-assisted contribution policy\n- [Good First Issues](docs/GOOD-FIRST-ISSUES.md) — Small scoped tasks for new contributors\n- [v0.2.0-alpha Notes](docs/releases/v0.2.0-alpha.md) — Release highlights and known limitations\n- [Roadmap](ROADMAP.md) — What's coming next\n\n---\n\n## Author\n\n**Solomon Steadman** —[@steadman](https://x.com/steadman) | [github.com/solstead](https://github.com/solstead)\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteadman-labs%2Fquaid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteadman-labs%2Fquaid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteadman-labs%2Fquaid/lists"}