{
  "markdown": "<!-- mcp-name: io.github.ygtalp/rawthink-mcp -->\n\n# RAWThink\n\nPersistent memory for AI thinking partnerships. A knowledge graph you can argue\nwith, search that spans every session you have ever had, and a record of not\njust what you decided but what you rejected.\n\nMCP server for Claude Code. Python, local, no cloud.\n\n---\n\n## The problem\n\nEvery conversation with an AI starts from nothing. You explain the same context,\nre-derive the same conclusions, and rediscover decisions you already made — and\nthe reasoning that produced them is gone the moment the window scrolls.\n\nChat history does not fix this. History is a transcript; what you need is\n*structure*: which ideas connect, which beliefs you have since abandoned, which\nalternatives you considered and dropped, and why.\n\nRAWThink keeps that structure in three layers, in files you own.\n\n## What it does\n\n**Hybrid semantic search** across every session and note — BGE-M3 dense\nembeddings and BM25 sparse vectors, fused with RRF. Ask \"what did I think about\nfree will?\" and get the passages, not a keyword match.\n\n**A temporal knowledge graph** where observations carry dates and status.\nBeliefs can be marked invalidated and linked to what replaced them, so the\narchive remembers not only what you think but what you used to think.\n\n**Session lifecycle** — a close command that exports the conversation, extracts\nentities into the graph, and writes a handoff the next session loads\nautomatically.\n\n**Activation decay** — unused knowledge fades on a ~23-day half-life, accessed\nknowledge stays warm. Old material is still there; it just stops crowding out\nwhat you are working on now.\n\n---\n\n## Quick start\n\n### Prerequisites\n\n- Python 3.10+\n- Docker for Qdrant — or set `QDRANT_PATH` for embedded mode\n- [Ollama](https://ollama.com) with `bge-m3`: `ollama pull bge-m3`\n\n### Install\n\n```bash\npip install rawthink-mcp\nrawthink-install                 # creates ~/rawthink-vault with everything inside\ncd ~/rawthink-vault\ndocker compose up -d             # starts Qdrant\n```\n\n`rawthink-install` writes the vault structure, `CLAUDE.md`,\n`THINKING_DIRECTIVES.md`, `SETUP.md`, `docker-compose.yml` and the `/rtclose`\ncommand. Use `rawthink-install --vault ~/my-vault` for a different location.\n\n### Register with Claude Code\n\n```bash\nclaude mcp add --scope user rawthink -- rawthink-mcp\n```\n\n### Check the install\n\n```bash\nrawthink-doctor\n```\n\nNine checks with a fix line for each failure: vault, graph schema, BM25 state\nformat, Qdrant, **index coverage**, vector dimension, Ollama, MCP registration.\n\nThe index coverage check is the one worth knowing about. Indexing can stop\npartway and leave a collection that looks healthy — it exists, it has points,\nqueries return results. They are results from part of the vault, and nothing\nelse tells you that.\n\n### Upgrading from 0.x\n\n**1.5.0 changed the graph schema and 2.0.0 changes the sparse index.**\nMigrate the graph before writing anything:\n\n```bash\npython -m rawthink_mcp.migrate --path vault/memory.jsonl --guess-domains --heal-dangling\n```\n\nThat is a dry run — it prints what would change and writes nothing. Read the\nreport, then re-run with `--apply`. A timestamped backup is taken first.\n\nThen re-encode the search index, because BM25 term IDs changed:\n\n```\nreindex(full=True)\n```\n\nA plain reindex skips unchanged chunks and will leave the old encoding in\nplace. `rawthink-doctor` tells you if this is still pending.\n\nSee [CHANGELOG.md](CHANGELOG.md) for what changed and why.\n\n---\n\n## Your first session\n\n```\n> search_thoughts(\"what have I decided about caching?\")\n\n> record_decision(\n    name=\"api/cache: read-through\",\n    domain=\"software\",\n    decided=\"read-through cache in front of the read model\",\n    because=\"the write path is already the bottleneck; adding invalidation there costs more\",\n    rejected=[\"write-through — couples the write path to cache health\",\n              \"no cache — p99 was 400ms against a 200ms SLO\"]\n  )\n```\n\nClose with `/rtclose`. It exports the conversation, extracts what is worth\nkeeping into the graph, and leaves a handoff for next time — which the next\nsession loads on its own.\n\n---\n\n## The schema, and why it looks like this\n\nThis is the part worth understanding, because it is what keeps the graph\nqueryable over years rather than months.\n\n### Role and subject are separate fields\n\n`entityType` answers **what role does this node play**. Closed list of ten:\n\n| type            | for                                                          |\n| --------------- | ------------------------------------------------------------ |\n| `decision`      | a choice made, with alternatives rejected                    |\n| `concept`       | an idea, theory, model, analogy                              |\n| `finding`       | something discovered or measured — a bug, a result, an audit |\n| `rule`          | a durable constraint or pattern to follow                    |\n| `open-question` | unresolved, waiting on evidence                              |\n| `artifact`      | a project, tool, document, feature, source                   |\n| `insight`       | a realisation that changed how something is seen             |\n| `task`          | a unit of intended work                                      |\n| `event`         | something that happened at a point in time                   |\n| `thing`         | a person, object or substance named directly                 |\n\n`domain` answers **what subject is it about**: `software`, `music`, `history`,\n`philosophy`, `health`, `writing`, `neuro`, `finance`, `personal`, `galaxy`.\n\nKeeping these apart is not tidiness. When one field carries both, the type list\ngrows by one entry per subject — a real vault reached 46 types this way, with\n`saglik-bulgusu`, `teknik-karar` and `bug-pattern` sitting next to `karar`. At\nthat point nothing can be filtered, because no two entries agree on what a type\nmeans.\n\n### Unknown relation types are rejected, not warned about\n\nCanonical vocabulary: `supports`, `contradicts`, `evolved_into`, `depends_on`,\n`exemplifies`, `part_of`, `caused_by`, `enables`, `supersedes`, `related_to`,\n`investigates`, `informs`, `uses`.\n\nClose synonyms fold automatically — `connected_to` → `related_to`, `aspect_of` →\n`part_of`. Anything else raises.\n\nAn earlier version accepted unknown types with a warning. Nothing acted on the\nwarning and 56 one-off types accumulated. **A warning that lets the write\nthrough is a decision to allow it, written in the voice of disapproval.**\n\n### Epistemic status defaults to unknown\n\n`assertion`, `hypothesis`, `speculation` — or `unknown` when unstated.\n\n`unknown` is deliberate. If a session did not establish something, recording it\nas an assertion promotes a claim nobody made. The migration follows the same\nrule: 144 entities with no epistemic field became `unknown`, not `assertion`.\n\n### Revise, do not delete\n\n```\n> revise(entity_name=\"api/cache: read-through\",\n         observations=[\"read-through cache in front of the read model\"],\n         superseded_by=\"moved to write-through after the read model split\",\n         superseding_entity=\"api/cache: write-through\")\n```\n\nThe old observation is marked invalidated, dated, and linked to what replaced\nit. Delete tools exist but sit outside the default agent-facing profiles: an\narchive that forgets its own reversals cannot answer the question it was kept\nfor.\n\n### Decisions record what was rejected\n\n`record_decision` stores `decided`, `because`, and `rejected` as separately\nqueryable observations. The rejected alternatives are the part worth keeping —\nwhat was chosen stays readable in the code forever, what was considered and\ndropped exists nowhere else. That is the question that gets asked six months\nlater.\n\n---\n\n## MCP tools\n\nTool definitions sit in the context window from the first token of a session,\nso the surface is a standing cost rather than a per-call one. Profiles load\nonly what a given step needs.\n\n```bash\nRAWTHINK_TOOL_PROFILE=recall   #  4 tools,  ~900 tokens — read-only\nRAWTHINK_TOOL_PROFILE=record   #  5 tools, ~1750 tokens — the write path\nRAWTHINK_TOOL_PROFILE=full     # 17 tools, ~4200 tokens — everything (default)\n```\n\nA tool outside the active profile stays an ordinary function — reachable from\nthe CLI and from tests. It simply is not in front of an agent that will not\ncall it.\n\n### Search\n\n| tool              | what it does                                                |\n| ----------------- | ----------------------------------------------------------- |\n| `search_thoughts` | Hybrid search. `mode=\"overview\"` gives one line per session |\n| `get_session`     | Full content of a session by ID                             |\n| `store_thought`   | Save a quick note as a qnote                                |\n| `reindex`         | Re-index the vault into Qdrant                              |\n\n### Graph — reading\n\n| tool           | what it does                                                                            |\n| -------------- | --------------------------------------------------------------------------------------- |\n| `search_nodes` | Bounded. Filters by `domain` and `entity_type`; reports `total_matched` and `truncated` |\n| `open_nodes`   | Specific entities with their relations                                                  |\n| `read_graph`   | Whole graph, paginated, with a summary mode                                             |\n\n### Graph — writing\n\n| tool                                                           | what it does                                                       |\n| -------------------------------------------------------------- | ------------------------------------------------------------------ |\n| `record`                                                       | Entities, relations and observations in one validated, atomic call |\n| `record_decision`                                              | A decision with its rejected alternatives                          |\n| `revise`                                                       | Mark observations superseded, link what replaced them              |\n| `create_entities` · `create_relations` · `add_observations`    | Lower-level equivalents                                            |\n| `invalidate_observations`                                      | Belief revision without the relation link                          |\n| `delete_entities` · `delete_observations` · `delete_relations` | `full` profile only                                                |\n\n`record()` validates the whole batch before writing any of it. A half-valid\nbatch writes nothing — a graph left in a state nobody asked for is worse than a\nrejected write. Relations may only point at entities that already exist or are\ncreated in the same call.\n\nEvery tool carries MCP annotations (`readOnlyHint`, `destructiveHint`,\n`idempotentHint`), so a host can tell deletion apart from search.\n\n---\n\n## Architecture\n\n```\nClaude Code\n    │  MCP (stdio)\n    ▼\nrawthink-mcp\n    ├── search  ──►  Qdrant        dense (BGE-M3) + sparse (BM25), RRF fusion\n    ├── graph   ──►  memory.jsonl  entities, relations, temporal observations\n    └── export  ──►  vault/        sessions, qnotes, handoffs as markdown\n                         │\n                    Ollama (bge-m3)\n```\n\nEverything runs locally. The vault is plain markdown with YAML frontmatter —\nopen it in Obsidian to browse visually, no plugins needed.\n\n### Why JSONL for the graph\n\nHuman-readable, git-diffable, no dependency. You can open it, read it, and see\na meaningful diff when it changes — which matters for something meant to hold\nyour reasoning.\n\nThe tradeoff is load time: the whole file is parsed per read. Fine at a few\nhundred entities, slower as it grows. Past tens of thousands, SQLite is the\nobvious next step.\n\n---\n\n## Session lifecycle\n\n```\nsession start          handoff loads automatically (SessionStart hook)\n      ↓\n  think together\n      ↓\n   /rtclose            export → extract entities → write handoff → update MEMORY.md\n```\n\n`/rtclose` exports the conversation to clean markdown, extracts entities and\nrelations through `record()`, writes a project-scoped handoff, and updates\n`MEMORY.md`.\n\nThe lifecycle commands currently require Claude Code. The search and graph\ntools work with any MCP client.\n\n---\n\n## Configuration\n\n| Setting               | Env var                          | Default                           |\n| --------------------- | -------------------------------- | --------------------------------- |\n| Vault path            | `RAWTHINK_VAULT`                 | `../vault`                        |\n| Knowledge graph file  | `MEMORY_FILE_PATH`               | `<vault>/memory.jsonl`            |\n| Qdrant URL            | `QDRANT_URL`                     | `http://localhost:6333`           |\n| Qdrant embedded path  | `QDRANT_PATH`                    | — (set it to skip Docker)         |\n| Ollama URL            | `OLLAMA_URL`                     | `http://localhost:11434`          |\n| Embedding model       | `OLLAMA_MODEL`                   | `bge-m3`                          |\n| Tool profile          | `RAWTHINK_TOOL_PROFILE`          | `full`                            |\n| Turkish normalization | `RAWTHINK_TURKISH_NORMALIZATION` | `false`                           |\n| Evaluation set        | `RAWTHINK_EVAL_GT`               | `tests/ground_truth.example.json` |\n\nVocabularies — `ENTITY_TYPES`, `DOMAINS`, `RELATION_TYPES`, `RELATION_ALIASES` —\nlive in `rawthink_mcp/config.py`. Adding a domain is a one-line change.\n\n---\n\n## Customization\n\n**`CLAUDE.md`** — the thinking companion's role, tone and modes.\n\n**`THINKING_DIRECTIVES.md`** — discipline for the partnership. Every rule was\nwritten after failing at it. Add your own; the only bad version of that file is\none followed without understanding why each rule exists.\n\nBoth are copied into your vault by `rawthink-install`. If you edit the repo\ncopies, run `python scripts/check_templates.py` — the installer embeds them, and\ntwo copies of one document drift silently.\n\n---\n\n## Known limitations\n\nStated plainly, because a README that lists only strengths is not much use.\n\n**Ollama being unavailable degrades to sparse-only.** The embedding cache helps\nrepeated queries; it is not a fallback. Retrieval quality drops noticeably.\n\n**Graceful shutdown is POSIX-only.** Signal handlers release the Qdrant\ndirectory lock and the graph file lock on SIGINT/SIGTERM. Windows has no real\nSIGTERM — a terminating client calls TerminateProcess and no handler runs — so\na hard stop there can leave a lock behind. Ctrl-C still unwinds, and\n`rawthink-doctor` reports the stale lock.\n\n**Load time grows with the graph.** The whole JSONL is parsed on the first read\nafter a change. Subsequent reads reuse a cache keyed on (mtime, size).\n\n**Search quality has not been benchmarked at scale.** The retrieval numbers\nthat used to be here were never re-measured, so they were removed rather than\ncarried forward. `tests/search_quality.py` runs against a synthetic vault and\nreports MRR/nDCG; point `RAWTHINK_EVAL_GT` at your own evaluation set for a\nnumber that means something for your data.\n\n---\n\n## Roadmap\n\n**Next** — graph visualisation, MCP-native session lifecycle so the close\ncommand is not Claude Code specific, support for more MCP clients, and a\nretrieval benchmark that runs on data anyone can regenerate.\n\n---\n\n## Contributing\n\nIssues and pull requests welcome.\n\nIf you change the schema, change `config.py`, the migration in `migrate.py`, and\nthe session-close instructions together. They are three views of one contract,\nand they drift apart quietly when they are not edited as a set.\n\n`docs/postmortem-bm25-term-drift.md` is the clearest example — a defect that\nlooked fine from every angle until someone evaluated the two retrievers\nseparately.\n\n## License\n\nMIT\n",
  "bytes": 15841,
  "sha": "1c82378a9811e50c2f2cf1759ded81b61410b3eeaeccc548fd6faa4dd3fb48e9",
  "repo_slug": "ygtalp/rawthink-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ygtalp_rawthink_mcp_ec076861/readme"
}