Metadata-Version: 2.4
Name: aidiary
Version: 0.2.0
Summary: Portable human-AI collaboration memory system with MCP server and knowledge graphs
Author: Yingding Wang
License-Expression: MIT
Keywords: mcp,memory,copilot,ai-agent,knowledge-graph
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: mcp
Requires-Dist: mcp>=1.27.0; extra == "mcp"
Provides-Extra: graphs
Requires-Dist: graphifyy[mcp]>=0.5.0; extra == "graphs"
Dynamic: license-file

# aidiary

A portable memory system for AI coding assistants — remember conventions, track anti-patterns, and build institutional knowledge that persists across sessions.

## What it does

aidiary gives your AI assistant a structured, persistent memory. Instead of starting every session cold, the assistant recalls your coding conventions, past mistakes, and project-specific knowledge. Entries are scored by confidence and verification count, stale knowledge gets flagged, and contradictions are detected automatically.

Works as an MCP server — any MCP-compatible tool (VS Code Copilot Chat, Claude Code, Cursor, etc.) can read and write memories through a standard protocol.

## Install

Requires: Python 3.12+

```bash
# Core memory system + MCP server
pip install aidiary[mcp]

# Optional: knowledge graph pipeline (requires graphifyy)
pip install aidiary[graphs]

# Both
pip install aidiary[mcp,graphs]
```

## Quick start

### 1. Scaffold a project

```bash
aidiary-init ./my-project
cd my-project
```

This creates `memories/` with starter files (conventions, workflow, anti-patterns, tools, project-setup) and an empty `output/` directory.

### 2. Install skills for your AI assistant

Skills teach your AI assistant decision-making principles — loaded automatically when the agent is about to make a recommendation. Zero always-on context cost.

```bash
aidiary vscode install        # VS Code Copilot → ~/.copilot/skills/
aidiary claude install        # Claude Code → ~/.claude/skills/
aidiary gemini install        # Gemini CLI → ~/.gemini/skills/
aidiary copilot install       # GitHub Copilot CLI
aidiary kiro install          # Kiro IDE
aidiary hermes install        # Hermes
```

What the skill contains: 5 core principles (empirical-first, ensemble, degrees-of-freedom, challenge-first, docs-first) + 5 real-world anti-patterns with corrections. See [Agent Skills standard](https://agentskills.io/).

### 3. Start the MCP server

```bash
memory-server --memories ./memories --output ./output
```

Or add to your editor's MCP config (VS Code example — `.vscode/mcp.json`):

```json
{
  "servers": {
    "memory": {
      "type": "stdio",
      "command": "memory-server",
      "args": ["--memories", "${workspaceFolder}/memories", "--output", "${workspaceFolder}/output"]
    }
  }
}
```

### 4. (Optional) Set up knowledge graphs

If you installed `aidiary[graphs]`, create a `graphs.toml` in your project root and build:

```bash
rebuild-graphs --code-only    # instant AST graph, no LLM needed
rebuild-graphs --status       # check freshness + staleness %
```

See the **Graph building workflow** section below for the full `graphs.toml` config format, staleness monitoring, and CLI reference.

> **Note:** `aidiary[graphs]` requires [graphifyy](https://pypi.org/project/graphifyy/). The memory system (`aidiary[mcp]`) works independently — graphs are optional.

### 5. Your first session

Tell your AI assistant to call `briefing` at session start. It returns top conventions, recent anti-patterns, and health warnings. After learning something, the agent calls `remember`. At session end, `reflect` summarizes what was learned.

```
Session 1 (cold start)         Session 2 (warm start)
  briefing → empty               briefing → 5 conventions, 1 anti-pattern
  work on task                    recall("dependency management") → 2 hits
  remember 3 conventions          verify existing entry
  record 1 mistake                learn 2 new things
  reflect → 4 entries             reflect → 7 entries, 1 verified
```

### Directory layout

```
my-project/
├── graphs.toml           # graph build config (optional)
├── memories/             # memory files (markdown only)
│   ├── conventions.md
│   ├── workflow.md
│   ├── anti-patterns.md
│   ├── tools.md
│   └── project-setup.md
└── output/               # all generated artifacts
    ├── memory-health.html
    └── graphs/           # knowledge graph outputs (optional)
        ├── code/
        │   ├── graph.json
        │   └── graph.html
        └── docs/
```

> **Warning:** Do **not** place non-markdown files in `memories/`. This directory is designed to be used as input for semantic graph generation. All generated output goes to `output/`.

> **Backup your memories.** Memory files use atomic writes (`tempfile` + `os.replace()`) to prevent corruption, but version control (`git`) provides the best protection for your `memories/` directory.

### CLI flags and environment variables

| Flag | Env var | Default | Purpose |
|------|---------|---------|---------|
| `--memories`, `-m` | `COPILOT_MEMORY_DIR` | `./memories` | Markdown memory files |
| `--output`, `-o` | `COPILOT_MEMORY_OUTPUT_DIR` | `./output` | Dashboard HTML and generated artifacts |

## What's new

### 0.2.0

**Production hardening + condensation + unified observatory + modular graph pipeline**

- **Atomic file writes** — `_safe_write()` now uses `tempfile.mkstemp()` + `os.replace()` (POSIX atomic). No data corruption on crash or disk-full.
- **`safe_int()` helper** — 9 crash sites across 6 modules protected from corrupted metadata. Corrupted `verified_count` no longer kills the MCP server.
- **`condense` MCP tool** (18th tool) — synthesize N related entries into 1 principle. 6 fidelity metrics (KCR/NKR/SR/ERR/TS/SMD), 7 safety guards (anti-pattern immunity, one-level-deep rule, circuit breaker, KCR reject/warn, NKR warn, SR warn, SMD pre-check). Archives originals with `condensed_into` lineage.
- **Principle maturity classification** — L1-L5 classifier (`classify_maturity()`). `remember`/`update` responses show maturity level. Soft warnings for bare rules (L2) missing reasoning.
- **Memory governance dashboard** — 4 new panels: maturity distribution (L1-L5 with targets), verification depth (4 buckets), action queue (drill-down with tool suggestions and pagination), graph health (optional).
- **Unified Knowledge Observatory** — multi-layer vis-network viewer: code (blue), docs (green), memory (purple) graphs + gold bridge edges. Layer toggles, search, minimap, zoom controls, click-to-filter. L1 keyword bridges auto-generated.
- **Modular graph pipeline** (Phase 2a + 2b) — `graphs.toml` config format with `[backends.*]` registry, `[ignore]` patterns, `[views.*]` declarative output. `backend_graphify.py` isolates all graphify imports. `pipeline.py` is a pure orchestrator. `rebuild-graphs --status --json`, `--refresh`, `--views-only`, `--no-views` flags. Cross-project `aidiary[graphs]` support.
- **Action queue pagination** — all tiers (core/mcp/graphs). Prev/Next/page-size controls for drill-down items. No more `[:5]` cap.
- **Light mode contrast** — graph background darkened (`#f0f2f5` → `#e0e3ea`) for better node visibility.
- **Script injection protection** — JSON in `<script>` tags escaped with `</` → `<\/` (OWASP).
- **Traceback logging** — MCP handler exceptions print full traceback to stderr.
- **Best-effort dashboard regen** — `briefing`/`reflect` dashboard auto-regen wrapped in try/except. Main output never lost.
- **MANIFEST.in** — skills `.md` files now included in sdist.
- **`graphifyy` version aligned** — `>=0.5.0` in both optional-deps and dev.
- **Tier isolation verified** — 12 core modules import without mcp/graphifyy (smoke test #66). 6 graphs modules import without graphifyy (smoke test #67). `backend_graphify.py` is the single isolation boundary.
- **74 smoke tests + 40 Playwright e2e tests**, all passing.

### 0.1.0

**Core memory system + MCP server + skills**

- **15 MCP tools** — `recall`, `remember`, `update`, `stage`, `review_staged`, `record_mistake`, `archive`, `restore`, `consolidate`, `briefing`, `reflect`, `health_report`, `dashboard`, `transfer_report`, `export_universal`.
- **Memory constitution** — write-time validation: size limits, forbidden content, duplicate detection, dedup guard.
- **Staging pipeline** — `stage` + `review_staged` with constitution validation, overlap detection, contradiction checks.
- **Memory health dashboard** — single-file HTML with summary cards, sortable entry table, distribution charts, anti-pattern timeline. Auto-generated at session start and end.
- **Session briefing** — top conventions, recent anti-patterns, health warnings at session start.
- **Session-end reflection** — summarizes what was learned, verified, and corrected.
- **Anti-pattern tracking** — episodic memory with correction links and supersession chains.
- **Cross-project transfer** — `scope: universal | project` metadata, `transfer_report` + `export_universal` tools.
- **Reflection hierarchy** — `reflections.md` with `derived_from` metadata for synthesized principles.
- **Contradiction detection** — keyword heuristic with negation-context polarity (Option A).
- **Self-critique in consolidation** — stale entry detection, merge suggestions, confidence mismatch flags.
- **Decision-principles skill** — bundled VS Code / Claude / Gemini skill with 5 principles + 5 anti-patterns. `aidiary vscode install` CLI with 6 platform targets.
- **`aidiary-init`** — scaffold a new project with starter memory files + output directory.
- **`rebuild-graphs`** (Phase 1) — config-driven graph rebuild with `--code-only`, `--build-only`, `--fresh` flags.
- **Production hardening** — path traversal protection, auto-create directories, `MANIFEST.in`, `--memories`/`--output` CLI flags with env var fallbacks.
- **79 tests**, all passing.

## What you get


**18 MCP tools** — `recall`, `remember`, `update`, `stage`, `review_staged`, `record_mistake`, `archive`, `restore`, `consolidate`, `condense`, `briefing`, `reflect`, `health_report`, `dashboard`, `list_topics`, `get_memory`, `transfer_report`, `export_universal`

**Memory condensation** — synthesize N related entries into 1 principle with fidelity metrics and safety guards. Anti-pattern immunity, one-level-deep rule, provisional status

**Session briefing** — top conventions, recent anti-patterns, health warnings, and quick stats at session start

**Staging pipeline** — new entries go through validation, overlap detection, and contradiction checks before committing

**Memory health dashboard** — single-file HTML with summary cards, sortable tables, and distribution charts. Auto-generated to `output/memory-health.html` at session start (`briefing`) and session end (`reflect`). Open it in any browser to review your memory health. Can also be triggered manually via the `dashboard` MCP tool. Includes governance panels (maturity distribution, verification depth, action queue with pagination) and a unified Knowledge Observatory (multi-layer graph viewer with search, minimap, and layer toggles).

**Anti-pattern tracking** — episodic memory for mistakes with correction links, so the same error isn't repeated

**Cross-project transfer** — entries tagged `universal` or `project`-scoped. Export universal knowledge for reuse across workspaces

**Session-end reflection** — summarizes what was learned, verified, and corrected during a session

**Decision-principles skill** — bundled [Agent Skills](https://agentskills.io/) standard skill that teaches your AI assistant 5 core decision-making principles (empirical-first, ensemble, degrees-of-freedom, challenge-first, docs-first). Auto-discovered by VS Code Copilot, Claude Code, Gemini CLI, and other compatible agents. Zero always-on context cost — loaded only when the agent is making a recommendation.

> **Why skills matter:** MCP tools are passive — the agent must call them explicitly. Skills are proactive — auto-loaded when relevant. Without skills, conventions exist in memory but don't fire at decision time. In baseline measurement, 30% of AI recommendations needed user correction due to greedy/local-optimum thinking. Skills address this by injecting decision principles exactly when the agent is about to make a recommendation.

### Install skills

Install decision-principles for all supported platforms — see **Quick start § Step 2** above for the full command list and platform targets.

```bash
aidiary vscode install      # VS Code → ~/.copilot/skills/
aidiary vscode uninstall    # remove
```

### Session lifecycle

```
Session start                          Session end
     │                                      │
     ▼                                      ▼
  briefing                               reflect
     │                                      │
     ├─ top conventions                     ├─ entries recorded today
     ├─ recent anti-patterns                ├─ entries verified today
     ├─ health warnings                     ├─ anti-patterns logged
     └─ auto-generates dashboard            └─ auto-generates dashboard
                                                 │
                                                 ▼
                                      output/memory-health.html
                                      (open in browser to review)
```

The dashboard at `output/memory-health.html` is regenerated automatically at every session start and end. No manual action needed — just open the file to see the latest health status.

For library users (not using MCP), generate the dashboard explicitly:

```python
from aidiary.dashboard import generate_dashboard

html = generate_dashboard(memories, fm)
(output_dir / "memory-health.html").write_text(html)
```

## How it works

Memories are plain markdown files with YAML metadata per entry (confidence, source, verified count, scope). No database, no embeddings, no external services — just files you can read, edit, and version-control.

The MCP server parses these files, provides keyword search with scoring, and enforces a constitution (write rules, size limits, forbidden content). A consolidation engine detects stale entries, confidence mismatches, and merge candidates.

### Using aidiary as a library

```python
from pathlib import Path
from aidiary.store import MemoryStore
from aidiary.search import search_memories
from aidiary.scoring import health_report
from aidiary.consolidate import consolidate
from aidiary.briefing import briefing
from aidiary.dashboard import generate_dashboard

# Point to your directories
memories_dir = Path("./memories")
output_dir = Path("./output")
output_dir.mkdir(exist_ok=True)

# Read and search memories
store = MemoryStore(memories_dir)
memories = store.load_all()
results = search_memories("dependency management", memories)

# Write a new entry
store.append(
    "conventions", "Pin exact versions",
    "Always pin exact versions in requirements files.",
    {"confidence": "high", "source": "observation"},
)

# Generate health report and dashboard
report = health_report(memories)
fm = store.load_frontmatter_only()
html = generate_dashboard(memories, fm)
(output_dir / "memory-health.html").write_text(html)

# Session briefing
summary = briefing(memories, fm)
```

### Memory lifecycle (library)

Beyond basic read/write, aidiary supports a full memory lifecycle:

```python
from aidiary.store import MemoryStore
from aidiary.search import search_memories
from aidiary.staging import stage, review_staged, list_staged
from aidiary.transfer import transfer_report, export_universal
from aidiary.condense import condense
from aidiary.reflect import session_reflect

store = MemoryStore(memories_dir)

# Upsert — update an existing entry (matched by heading, case-insensitive)
store.append(
    "conventions", "Pin exact versions",
    "Pin exact versions in ALL requirements files. Never use floating ranges.",
    {"confidence": "high", "source": "correction"},
    upsert=True,  # updates if heading exists, creates if not
)

# Search — returns dicts with file, heading, score, body
results = search_memories("exact versions", store.load_all())
# [{"file": "conventions", "heading": "Pin exact versions", "score": 2, ...}]

# Archive — move stale entries to archive.md
store.archive_section("tools", "Deprecated tool")

# Restore — bring archived entries back
store.restore_section("Deprecated tool")

# Stage — queue entries for human review before committing
memories = store.load_all()
result = stage(
    "New pattern observed", "Always use dataclasses for data models.",
    "conventions",
    {"confidence": "medium", "source": "observation"},
    store=store, memories=memories,
)
# result = {"status": "staged", "annotations": [...]}

# Review staged entries
staged = list_staged(store=store)
review_staged("New pattern observed", "promote", store=store)  # or "reject"

# Transfer — identify entries that can move to other projects
report = transfer_report(store.load_all())  # markdown summary
json_export = export_universal(store.load_all())  # JSON manifest

# Condense — synthesize N related entries into 1 principle
memories = store.load_all()
result = condense(
    entries=["Pin exact versions", "Never use floating ranges"],
    condensed_heading="Dependency version pinning",
    condensed_body="Always pin exact versions in all requirements files — because floating ranges break silently across environments.",
    target_file="conventions",
    metadata={"confidence": "high", "source": "reflection", "scope": "universal"},
    store=store, memories=memories,
)
# result = {"status": "condensed", "metrics": {"kcr": 0.85, ...}, "archived": [...]}

# Session-end reflection
memories = store.load_all()
fm = store.load_frontmatter_only()
reflection = session_reflect(memories, fm, store=store)
```

### Memory file format

```markdown
---
topic: conventions
entry_count: 3
last_updated: 2026-04-18
---
# Conventions

## Pin exact versions
- confidence: high
- source: observation
- scope: universal
- verified_count: 5
- last_verified: 2026-04-18

Always pin exact versions in requirements files.
```

## Connect your AI assistant

### How the command works

After `pip install aidiary[mcp]`, the `memory-server` command is available in the active Python environment. There are two ways to invoke it:

```bash
# Option 1: entry point (if installed globally or via pipx)
memory-server --memories ./memories --output ./output

# Option 2: full venv path (for project-local venvs)
/path/to/project/.venv/bin/memory-server --memories ./memories --output ./output

# Option 3: python -m (always works)
/path/to/project/.venv/bin/python -m aidiary.server ./memories
```

> **Note:** When using `python -m aidiary.server`, the first positional argument is the memories directory. The `--memories` / `--output` flags only work with the `memory-server` entry point.

### MCP configuration by editor

**VS Code (GitHub Copilot)** — `.vscode/mcp.json`:

```json
{
  "servers": {
    "copilot-memory": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/bin/memory-server",
      "args": ["--memories", "${workspaceFolder}/memories", "--output", "${workspaceFolder}/output"]
    }
  }
}
```

> Use the full venv path for `command` so VS Code finds the right Python environment. If installed globally via `pipx`, you can use just `"command": "memory-server"`.

**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "copilot-memory": {
      "command": "/ABSOLUTE/PATH/TO/.venv/bin/memory-server",
      "args": ["--memories", "/ABSOLUTE/PATH/TO/memories", "--output", "/ABSOLUTE/PATH/TO/output"]
    }
  }
}
```

> Claude Desktop requires **absolute paths** — no `~` or relative paths. Use `which memory-server` to find the full path.

**Cursor** — `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "copilot-memory": {
      "command": "/ABSOLUTE/PATH/TO/.venv/bin/memory-server",
      "args": ["--memories", "./memories", "--output", "./output"]
    }
  }
}
```

### Agent prompt template

Add this to your project instructions (`.github/copilot-instructions.md`, `CLAUDE.md`, or equivalent). See **Tell the agent about your memory system** in the Knowledge graphs section below for the full template including graph query guidance.

### What happens when the agent uses memory

```
┌─────────────────────────────────────────────────────────────────┐
│                    Agent Session Flow                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Session starts                                              │
│     │                                                           │
│     ▼                                                           │
│  ┌──────────┐   MCP call    ┌─────────────────────────────┐     │
│  │  Agent   │──────────────▶│  briefing()                 │     │
│  └──────────┘               │  → top conventions          │     │
│     │                       │  → recent anti-patterns     │     │
│     │  ◀────────────────────│  → health warnings          │     │
│     │  (agent reads context)│  → auto-generates dashboard │     │
│     │                       └─────────────────────────────┘     │
│     ▼                                                           │
│  2. Agent works on a task                                       │
│     │                                                           │
│     ├──▶ recall("dependency management")                        │
│     │    → returns matching entries ranked by relevance         │
│     │                                                           │
│     ├──▶ remember(file="conventions", heading="Use uv", ...)    │
│     │    → validates via constitution → writes to markdown      │
│     │                                                           │
│     ├──▶ record_mistake(heading="Used wrong venv", ...)         │
│     │    → writes to anti-patterns.md with correction link      │
│     │                                                           │
│     ├──▶ stage(heading="New pattern observed", ...)             │
│     │    → overlap check → contradiction check → staging.md     │
│     │                                                           │
│     ▼                                                           │
│  3. Session ends                                                │
│     │                                                           │
│     ▼                                                           │
│  ┌──────────┐   MCP call    ┌─────────────────────────────┐     │
│  │  Agent   │──────────────▶│  reflect()                  │     │
│  └──────────┘               │  → entries recorded today   │     │
│                             │  → entries verified today   │     │
│                             │  → consolidation suggestions│     │
│                             │  → auto-generates dashboard │     │
│                             └─────────────────────────────┘     │
│                                        │                        │
│                                        ▼                        │
│                             output/memory-health.html           │
│                             (human opens in browser)            │
└─────────────────────────────────────────────────────────────────┘
```

### Memory grows across sessions

```
Session 1          Session 2          Session 3
   │                  │                  │
   ▼                  ▼                  ▼
briefing (empty)   briefing (5)       briefing (12)
   │                  │                  │
   ├ learn 3 things   ├ recall + verify  ├ recall + verify
   ├ 1 mistake        ├ learn 2 more     ├ detect contradiction
   │                  ├ 1 mistake        ├ archive stale entry
   ▼                  ▼                  ▼
reflect            reflect             reflect
   │                  │                  │
   ▼                  ▼                  ▼
5 entries          9 entries           12 entries
0 verified         3 verified          6 verified
1 anti-pattern     2 anti-patterns     2 anti-patterns (1 archived)
```

Each session builds on the last. The agent starts faster, makes fewer repeated mistakes, and the knowledge base self-maintains through verification and consolidation.

### Three layers of AI assistant customization

```
┌────────────────────────────────────────────────────────┐
│ Layer 1: Skills (proactive — zero always-on cost)      │
│ Auto-loaded when relevant. Decision principles,        │
│ domain expertise. No manual recall needed.             │
├────────────────────────────────────────────────────────┤
│ Layer 2: MCP Server (passive — on-demand tools)        │
│ recall, remember, stage, reflect, briefing, etc.       │
│ Agent calls tools when it needs memory access.         │
├────────────────────────────────────────────────────────┤
│ Layer 3: Instructions (static — always-on context)     │
│ copilot-instructions.md, CLAUDE.md, AGENTS.md          │
│ Tells the agent about the memory system.               │
└────────────────────────────────────────────────────────┘
```

Skills are the most efficient layer — loaded only when relevant, zero context cost when idle. The MCP server provides the tools. Instructions tell the agent to use them.

## Knowledge graphs (optional)

aidiary can build knowledge graphs from your code, docs, and memory files — giving your AI assistant a concept network to query for architectural decisions, recall augmentation, and staging validation.

```bash
pip install aidiary[graphs]
```

> **Graphs are optional.** The memory system (`aidiary[mcp]`) works without graphs. Install `aidiary[graphs]` only if you want knowledge graph features. The graphify backend is lazy-loaded — it's only imported when you run `rebuild-graphs`.

### Graph building workflow

```bash
# 1. Create a graphs.toml config in your project root
cat > graphs.toml << 'EOF'
project = "my-project"
default_backend = "graphify"

[backends.graphify]
ignore_filename = ".graphifyignore"

[ignore]
patterns = ["**/__pycache__/", "**/__init__.py"]

[staleness]
warn_threshold = 50    # % of semantic graphs stale → ⚠ warning
error_threshold = 100  # % stale → 🔴 action required

[graphs.code]
input = "src/"
output = "output/graphs/code/"
method = "ast"

[graphs.docs]
input = "docs/"
output = "output/graphs/docs/"
method = "semantic"
EOF

# 2. Build graphs
rebuild-graphs                    # build all graphs
rebuild-graphs --code-only        # AST only (instant, no LLM)

# 3. Check status — includes staleness % per graph
rebuild-graphs --status
# Output:
#   Graph    Type       Nodes  Edges  Communities  Cache              Stale
#   code     instant      231    406           11  ✓ always fresh          —
#   docs     assisted     141    142           31  ⚠ stale              100%
#   Overall: 🔴 100% stale (2/2 semantic graphs)

# 4. Machine-readable for AI agents (includes staleness thresholds)
rebuild-graphs --status --json

# 5. Get fix guidance for stale graphs
rebuild-graphs --refresh

# 4. Views
rebuild-graphs --views-only       # regenerate views without rebuilding
rebuild-graphs --no-views         # build graphs only, skip views
```

### Multi-backend architecture

`graphs.toml` supports multiple backends. Today graphify is the default; future backends (tree-sitter, sentence-transformers, CLIP, node2vec) plug in via the same config:

```toml
# Future: same input, different backends
# [backends.text-embed]
# model = "all-MiniLM-L6-v2"
# dimensions = 384
#
# [graphs.doc-vectors]
# input = "docs/"
# output = "output/embeddings/docs/"
# backend = "text-embed"
# method = "sentence-transformer"
```

### Module structure

```
aidiary/graphs/
├── config.py             # TOML loader (generic, no backend imports)
├── ignore.py             # pattern merge + write + match
├── pipeline.py           # orchestrator (zero backend imports)
├── backend_graphify.py   # graphify-specific (all graphify.* imports)
├── views.py              # view dispatcher
├── view_json.py          # JSON summary renderer
└── cli.py                # argparse
```

All graphify imports live in `backend_graphify.py`. The orchestrator, config, ignore, views, and CLI have zero backend imports — swapping backends means adding a new `backend_<name>.py` file and a `[backends.<name>]` section in `graphs.toml`.

### Serve graphs via MCP

After building, expose your graphs to the AI assistant via [graphify's MCP server](https://pypi.org/project/graphifyy/). Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "memory": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/bin/memory-server",
      "args": ["--memories", "${workspaceFolder}/memories", "--output", "${workspaceFolder}/output"]
    },
    "code-graph": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/bin/python",
      "args": ["-m", "graphify.serve", "${workspaceFolder}/output/graphs/code/graph.json"]
    },
    "docs-graph": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/bin/python",
      "args": ["-m", "graphify.serve", "${workspaceFolder}/output/graphs/docs/graph.json"]
    }
  }
}
```

Each graph MCP server provides tools like `god_nodes`, `get_neighbors`, `shortest_path`, `query_graph` — the AI agent uses these for architectural analysis, concept discovery, and coupling checks.

> **After rebuilding graphs**, restart MCP servers. They load `graph.json` once at startup. Use Cmd+Shift+P → "MCP: Restart All Servers" in VS Code.

### Tell the agent about your memory system

Add this to your project instructions (`.github/copilot-instructions.md` for VS Code, `CLAUDE.md` for Claude Code):

```markdown
## Memory System

Call `briefing` at the start of every conversation.

| Task complexity | Action |
|----------------|--------|
| Any conversation | **`briefing`** — always, as the first action |
| Quick question | `recall` with relevant keywords before acting |
| Multi-step work | `briefing` → then `recall` as needed |
| Decision-making | `recall` → rethink → present options |

### During work
- Before acting on a topic, call `recall` with relevant keywords
- After learning something new, call `remember`
- After making a mistake, call `record_mistake`

### Session end
- Call `reflect` to summarize what was learned

### Knowledge graphs (if configured)
Before any architectural decision or refactoring, query the graph:
- `god_nodes` — most-connected concepts (start here)
- `get_neighbors` — what connects to the concept you're changing
- `shortest_path` — how two concepts relate
```

### Decision principles and custom skills

The bundled decision-principles skill teaches your AI assistant 5 core patterns:

| Principle | What it prevents |
|-----------|-----------------|
| Empirical-first | Building features without data |
| Ensemble | Locking into one approach |
| Degrees of freedom | Popularity bubbles, feedback loops |
| Challenge-first | Greedy/local-optimum decisions |
| Docs-first | Jumping to implementation without design |

To create your own custom skills, follow the [Agent Skills standard](https://agentskills.io/). Place a `SKILL.md` file with YAML frontmatter (`name`, `description`) in `~/.copilot/skills/<skill-name>/`.

### Full setup walkthrough

```
1. pip install aidiary[mcp,graphs]     Install package
2. aidiary-init ./my-project           Scaffold memories + output
3. aidiary vscode install              Install decision skill
4. Create graphs.toml                  Configure graph builds
5. rebuild-graphs --code-only          Build code graph (instant)
6. Add MCP configs to mcp.json         Memory server + graph servers
7. Add instructions to copilot-instructions.md
8. Start coding — agent calls briefing, recall, remember, reflect
```

## Tech stack

Python 3.12+ · MCP protocol · Markdown + YAML metadata · No external dependencies (base package). Optional: `mcp` library for MCP server.

## License

MIT

## Author

[Yingding Wang](https://github.com/yingding/)
