# a-local-memory

**English** | [中文版](https://unpkg.com/a-local-memory/README.zh-CN.md)

> Status: Design phase (spec v1) — see `docs/superpowers/specs/2026-08-02-a-local-memory-design.md` in the repository

A standalone **knowledge hub + code-relation orchestrator**. It exposes a single MCP entry point so AI coding agents (Codex, Claude Code) can precisely retrieve team-curated markdown knowledge and code relationships while writing code.

## Goals

- **Knowledge never lost** — knowledge docs live with each consuming project, versioned and reviewed together with the code.
- **Auto-evolving** — parsing, indexing, freshness checks, and health checks run automatically; content stays human-curated.
- **Precise retrieval** — MCP-based two-stage search, plus symbol-level relations delegated to LSP / codegraph MCPs.
- **Token-efficient** — metadata cards by default; full sections fetched on demand.

## How it works (overview)

- Consuming projects keep knowledge in `docs/knowledge/` (configurable via `.a-local-memory.yaml`, with glob matching).
- The hub registers projects in `projects.yaml`, indexes markdown into SQLite (plus an `index.json` export), and serves a single MCP.
- `doctor` checks sub-MCP health (LSP / codegraph), reports non-compliant docs, and drives an automated fix loop through a headless executor.

## Install

```bash
npm install -g a-local-memory
```

This installs two commands: `alm` (indexer CLI) and `alm-mcp` (MCP server).

## Usage (M1)

```bash
npm install
npm run build
echo 'projects:
  - id: my-service
    root: ../my-service' > projects.yaml
node dist/cli.js rebuild   # 索引所有注册项目 + 导出 index.json
node dist/cli.js status    # 查看各项目/分支文档数
```

Knowledge lives in each consuming project's `docs/knowledge/` (override via `.a-local-memory.yaml`, glob supported).
When installed globally, run `alm rebuild` / `alm status` from your working directory instead.

## MCP (M2)

```bash
npm run build
node dist/mcp/server.js   # stdio MCP server
```

Tools: `knowledge_search` (metadata cards), `read_section` (on-demand content), `projects` (registered projects).
When installed globally, the server command is simply `alm-mcp`.

Codex: add to `~/.codex/config.toml`:

```toml
[mcp_servers.a-local-memory]
command = "alm-mcp"
```

Claude Code: add to `.mcp.json`:

```json
{
  "mcpServers": {
    "a-local-memory": {
      "command": "alm-mcp"
    }
  }
}
```

## Status

Design phase. Implementation milestones M1–M5 are defined in `docs/superpowers/specs/2026-08-02-a-local-memory-design.md` in the repository.