# Aletheia

> Aletheia is an MCP server for knowledge and memory. Project memory for coding agents that re-checks each memory against the code on recall. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Platforms:** macOS, Windows, Linux, CLI
- **Website:** https://aletheia.firattunaarslan.me
- **Repository:** https://github.com/firatmio/aletheia
- **MCP Registry name:** io.github.firatmio/aletheia
- **Categories:** [knowledge and memory](https://ai-powered.com/categories/knowledge-and-memory), [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

The idea behind Aletheia is that a wrong memory is worse than none. Ordinary memory tools rank by similarity, so an outdated note looks as relevant as the fact that replaced it. Here each memory is a claim plus anchors, such as a function that must still exist, a line that must still match or a file that must still be present, and these are checked on every recall without model calls, embeddings or network access. A memory whose evidence broke is hidden and the agent gets a one-line note.

When Go code moves unchanged to another file, the memory follows and is shown as moved. Recall returns pointers computed from the current files, such as a test file and line number. When the agent stops, the session transcript is read to record which files the task changed so the next similar task starts there. Replaced memories are superseded and long-stale ones archived, never deleted. Memories are plain Markdown in a .aletheia folder you can commit.

It ships as a single binary, installable through npm, go install, Scoop or Homebrew, with a Claude Code plugin and hooks. The site reports benchmark runs with Claude Code where tasks changed by between minus 22% and minus 7%, one run each, and no saving on small tidy code.

## Features

- **Evidence-backed memories:** Each memory carries anchors checked against the code.
- **Stale memories hidden:** Broken evidence keeps a fact out of the agent's context.
- **Move tracking:** Memories follow Go declarations that move between files.
- **Line pointers:** Recall points to exact lines computed from current files.
- **Auto-written maps:** Session transcripts record which files a task touched.
- **Plain Markdown storage:** Memories live in .aletheia and can be committed.

## Good for

- Stop an agent re-reading the same files every session
- Share verified project knowledge with a team through git
- Avoid building on facts that stopped being true
- Start repeat tasks from the files last changed

## Install

### Claude Code (Terminal)

```sh
claude mcp add aletheia -- npx -y @firatmio/aletheia
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "aletheia": {
      "command": "npx",
      "args": [
        "-y",
        "@firatmio/aletheia"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "aletheia": {
      "command": "npx",
      "args": [
        "-y",
        "@firatmio/aletheia"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "aletheia": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@firatmio/aletheia"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "aletheia": {
      "command": "npx",
      "args": [
        "-y",
        "@firatmio/aletheia"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "aletheia": {
      "command": "npx",
      "args": [
        "-y",
        "@firatmio/aletheia"
      ]
    }
  }
}
```

## FAQ

### Does it use embeddings or model calls?

No. Anchor checks are mechanical with no model calls, embeddings or network.

### Where are memories stored?

As Markdown files in a .aletheia folder in the project.

### How is it installed?

npm, go install, Scoop, Homebrew or a prebuilt release; or via the Claude Code plugin.

### Does it always save effort?

The published runs show savings on some tasks and none on small, tidy code.

### How do I add Aletheia to Claude Code?

Run this command in your terminal: claude mcp add aletheia -- npx -y @firatmio/aletheia

### What are the best alternatives to Aletheia?

The closest alternatives to Aletheia are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

## Where this comes from

- Description: written from the project's README and the project's website.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/aletheia
