Add graph-first routing and instruction packaging

.github/copilot-instructions.md

@@ -0,0 +1,27 @@
+# Copilot Repository Instructions
+
+This repository is a graph-first codebase analysis and memory tool.
+
+## Default Behavior
+
+- Use `codebase-memory-mcp` first for structure, callers, dependencies, architecture, impact, and dead code.
+- Use `search_code` only for literal text, strings, config values, and non-structural lookup.
+- Run `list_projects` before structural questions.
+- Run `index_repository` when the repo is missing or clearly stale.
+
+## What to Prefer
+
+- `get_architecture` for repo orientation.
+- `search_graph` for symbol discovery.
+- `trace_path` for callers/callees and blast radius.
+- `detect_changes` for git-diff impact.
+- `query_graph` for cross-service or multi-hop questions.
+- `manage_adr` for durable architectural decisions.
+- `ingest_traces` for runtime evidence.
+
+## What Not to Do First
+
+- Do not start with shell grep when graph data can answer the question.
+- Do not treat chat memory as the source of truth for repo structure.
+- Do not split structural analysis across multiple guesses when a graph query is available.
+

AGENTS.md

@@ -0,0 +1,21 @@
+# Agent Routing
+
+This repo uses `codebase-memory-mcp` as the default structural discovery tool.
+
+## Use Memory First
+
+- Use `list_projects`, `get_architecture`, `search_graph`, `trace_path`, and `get_code_snippet` before raw file search when the task is about structure.
+- Use `detect_changes` when you need impact from a diff.
+- Use `query_graph` for multi-hop or cross-service questions.
+- Use `search_code` or shell search only for literal strings, config values, or non-code files.
+
+## Persisted Knowledge
+
+- Put durable repo knowledge in ADRs, docs, or graph-backed memory.
+- Do not rely on chat history for architectural facts.
+
+## Copilot and Claude
+
+- For GitHub Copilot repo instructions, use `.github/copilot-instructions.md`.
+- For Claude-style repo instructions, keep `CLAUDE.md` current.
+

CLAUDE.md

@@ -10,6 +10,14 @@ Multi-language codebase analysis and memory system implementing the Model Contex
 
 **Derivative Work**: This project is a security-hardened derivative of [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) by DeusData (MIT License). When modifying LICENSE, README, or attribution documentation, preserve both original copyright (DeusData) and derivative work copyright (Nathan Gallo / ngallodev-software). See NOTICE file for modification details.
 
+## Graph-First Routing
+
+- Use `codebase-memory-mcp` first for structure, callers, dependencies, architecture, impact analysis, dead code, and repo orientation.
+- Use `search_code` or shell text search only for literals, config keys, error strings, or non-code files.
+- Run `list_projects` before structural work; reindex when the project is missing or stale.
+- Use `get_architecture` and `trace_path` before guessing about service boundaries or dependencies.
+- Keep durable repo knowledge in graph artifacts, ADRs, or docs instead of chat memory.
+
 ## Build Commands
 
 ```bash

copilot-skill/SKILL.md

@@ -14,6 +14,18 @@ Use MCP server `copilot-memory-mcp` for precise structural code analysis.
 
 Graph tools return precise structural results in ~500 tokens vs ~80K for grep.
 
+## Tool Routing
+
+- Use graph tools first for structure, callers, dependencies, architecture, and impact.
+- Use `search_code` only for literal text, config, strings, and non-structural lookup.
+- Run `list_projects` before structural questions; run `index_repository` if the repo is missing.
+- Use `get_architecture` first when you need a repo overview.
+- Use `trace_path` for callers/callees and blast-radius questions.
+- Use `manage_adr` for durable architectural decisions, not chat-only notes.
+- Use `ingest_traces` for runtime evidence and postmortem analysis.
+- Use `index_status` when indexing is slow, incomplete, or suspicious.
+- Use `delete_project` only for operational cleanup.
+
 ## When to Use
 
 **Prefer this MCP server over grep/find when:**

docs/codebase-memory-tooling-analysis.md

@@ -0,0 +1,177 @@
+# Codebase Memory Tooling Analysis
+
+This document reviews how `copilot-memory-mcp` is currently guided to use `codebase-memory-mcp` and related memory tooling, what is missing, and what is worth changing.
+
+## Bottom Line
+
+- The repo already has a usable Copilot skill in [copilot-skill/SKILL.md](/lump/apps/copilot-memory-mcp/copilot-skill/SKILL.md).
+- The skill already lists the full `codebase-memory-mcp` tool set, so the gap is not missing tool inventory.
+- The real gap is routing and prompting: the repo does not strongly tell agents when to use the graph backend first, when to reindex, and when to fall back to text search.
+- The `codebase-memory-mcp` repository itself does not appear to carry its own `AGENTS.md` or `SKILL.md` files, so there is nothing obvious to mirror from that repo into this one.
+- The repo now ships repo-level routing surfaces: [AGENTS.md](/lump/apps/copilot-memory-mcp/AGENTS.md), [`.github/copilot-instructions.md`](/lump/apps/copilot-memory-mcp/.github/copilot-instructions.md), and [docs/instructions/memory-routing.md](/lump/apps/copilot-memory-mcp/docs/instructions/memory-routing.md).
+- Serena already has the right conceptual split documented, but its entry files still do not give a strong enough “graph first” reminder for structural work.
+
+## What I Checked
+
+- Indexed this repo with `codebase-memory-mcp`.
+- Compared the current repo’s local guidance files:
+  - [CLAUDE.md](/lump/apps/copilot-memory-mcp/CLAUDE.md)
+  - [copilot-skill/SKILL.md](/lump/apps/copilot-memory-mcp/copilot-skill/SKILL.md)
+- Checked the `codebase-memory-mcp` checkout for `AGENTS.md`, `SKILL.md`, and similar agent files.
+- Checked the Serena checkout for its own entry files and decision docs about Serena vs `codebase-memory-mcp`.
+
+## Findings
+
+### 1. The repo already exposes the full MCP tool catalog in the Copilot skill
+
+`copilot-skill/SKILL.md` already names the 14 MCP tools:
+
+- `index_repository`
+- `index_status`
+- `list_projects`
+- `delete_project`
+- `search_graph`
+- `search_code`
+- `trace_path`
+- `detect_changes`
+- `query_graph`
+- `get_graph_schema`
+- `get_code_snippet`
+- `get_architecture`
+- `manage_adr`
+- `ingest_traces`
+
+So the problem is not “missing tools.” The problem is that the skill mostly teaches the tools by listing them, not by enforcing a decision flow.
+
+### 2. The repo-local onramp is too weak for graph-first behavior
+
+[CLAUDE.md](/lump/apps/copilot-memory-mcp/CLAUDE.md) gives a broad architecture overview, but it does not act as a strong behavioral guardrail for agents deciding how to explore the repo.
+
+That means an agent can still drift into:
+
+- `rg` first, when graph structure is the better answer
+- answering architecture questions from memory instead of live graph data
+- forgetting to reindex before structural work
+- using `search_code` for structural queries instead of text-only searches
+
+### 3. The `copilot-skill` file is good but not opinionated enough
+
+What it does well:
+
+- It explicitly recommends `search_graph`, `trace_path`, `query_graph`, and `detect_changes`.
+- It explains when grep/find is appropriate.
+- It already covers the main exploratory workflow.
+
+What it still under-emphasizes:
+
+- `index_status` as a normal health check after indexing
+- `delete_project` as an operational cleanup tool
+- `manage_adr` as a persistent architectural-memory tool
+- `ingest_traces` as a runtime-analysis tool, not just a novelty
+- the fact that graph tools should be the default for structure, not just an option
+- the fact that `search_code` is for literal text search, not structural discovery
+
+### 4. `codebase-memory-mcp` itself does not appear to ship extra agent files
+
+In the `codebase-memory-mcp` checkout, I did not find any repo-local `AGENTS.md`, `SKILL.md`, or `skill.md` files.
+
+That means:
+
+- there is no hidden upstream agent contract to copy
+- there is no upstream skill pack to import wholesale
+- this repo should keep its own guidance lightweight and explicit instead of trying to mirror nonexistent upstream files
+
+### 5. Serena already has the right strategic split, but it could be operationalized better
+
+The Serena repo already says the right thing in principle: use Serena for live coding and `codebase-memory-mcp` for structural memory.
+
+Relevant files:
+
+- [AGENTS.md](/lump/apps/serena/AGENTS.md)
+- [CLAUDE.md](/lump/apps/serena/CLAUDE.md)
+- [docs/05-decisions/0002-serena-and-codebase-memory-mcp-recommendation.md](/lump/apps/serena/docs/05-decisions/0002-serena-and-codebase-memory-mcp-recommendation.md)
+
+The missing piece is a stronger runtime reminder in the entry files, not a new conceptual doc.
+
+## Evaluation
+
+### Worth doing
+
+1. Add a small graph-first reminder block to [CLAUDE.md](/lump/apps/copilot-memory-mcp/CLAUDE.md).
+2. Tighten [copilot-skill/SKILL.md](/lump/apps/copilot-memory-mcp/copilot-skill/SKILL.md) so it tells the model when to use each tool family, not just what each tool is called.
+3. Add similar “graph first, Serena second” reminders to Serena’s [AGENTS.md](/lump/apps/serena/AGENTS.md) and [CLAUDE.md](/lump/apps/serena/CLAUDE.md).
+4. Keep the existing `/home/nate/.codex/AGENTS.md` codebase-memory directive, because it is already the strongest global reminder we have.
+
+### Not worth doing
+
+1. Creating a brand-new skill just to restate the existing tool list.
+2. Inventing a separate “Serena memory” replacement for `codebase-memory-mcp`.
+3. Duplicating the same graph-first advice in too many files.
+4. Rewriting the codebase-memory repo itself to add agent files when it currently does not ship any.
+
+## Proposals
+
+### Proposal 1: Add a short repo-local graph-first block to `CLAUDE.md`
+
+Add a compact section near the top of [CLAUDE.md](/lump/apps/copilot-memory-mcp/CLAUDE.md) that says:
+
+- use `codebase-memory-mcp` first for structure, callers, dependencies, architecture, impact analysis, and dead code
+- use `search_code` / grep only for literals, config values, and non-code text
+- run `list_projects` before any structural question
+- reindex when the project is missing or clearly stale
+
+This is the highest-value change because it affects every Codex-style session without requiring a separate skill lookup.
+
+### Proposal 2: Make `copilot-skill/SKILL.md` more operational
+
+Keep the existing tool list, but add short “when to use” notes for the tools that are currently buried in the list:
+
+- `index_status` for indexing progress and failure triage
+- `delete_project` for cleanup and repo replacement
+- `manage_adr` for durable architectural decisions
+- `ingest_traces` for runtime evidence and postmortem data
+- `get_architecture` as the first stop for repo orientation
+
+Also add one explicit sentence that says:
+
+- graph tools are the default for structural questions
+- `search_code` is for literal text search, not structure
+
+### Proposal 3: Add a Serena-side reminder, not a new Serena subsystem
+
+Update Serena’s entry files to make the split impossible to miss:
+
+- [AGENTS.md](/lump/apps/serena/AGENTS.md)
+- [CLAUDE.md](/lump/apps/serena/CLAUDE.md)
+
+Recommended reminder:
+
+- if the task is “what is this codebase / who calls this / what changed structurally”, ask `codebase-memory-mcp` first
+- if the task is “edit this code now”, use Serena
+- if the answer should survive beyond the session, write it into durable memory or ADRs, not only chat
+
+### Proposal 4: Prefer one central hook over many scattered ones
+
+The best long-term pattern is:
+
+- one global reminder in `/home/nate/.codex/AGENTS.md`
+- one repo-local reminder in [CLAUDE.md](/lump/apps/copilot-memory-mcp/CLAUDE.md)
+- one skill entry point in [copilot-skill/SKILL.md](/lump/apps/copilot-memory-mcp/copilot-skill/SKILL.md)
+
+That is enough. More layers than that are likely to become noise.
+
+## Recommendation
+
+If we do anything, do these in order:
+
+1. Add the repo-local graph-first reminder to [CLAUDE.md](/lump/apps/copilot-memory-mcp/CLAUDE.md).
+2. Tighten [copilot-skill/SKILL.md](/lump/apps/copilot-memory-mcp/copilot-skill/SKILL.md) with tool-specific usage cues.
+3. Add the same reminder pattern to Serena’s [AGENTS.md](/lump/apps/serena/AGENTS.md) and [CLAUDE.md](/lump/apps/serena/CLAUDE.md).
+
+Everything else is optional polish.
+
+## Notes
+
+- The repo was reindexed with `codebase-memory-mcp` before this analysis.
+- I did not find a separate `AGENTS.md` or `SKILL.md` inside the `codebase-memory-mcp` checkout itself.
+- The current repo already has the right tools; it mainly needs stronger prompting and a better default decision tree.

docs/install-copilot.md

@@ -53,9 +53,17 @@ make clean && make -j2
 - installs the binary
 - configures GitHub Copilot MCP settings in VS Code
 - installs `~/.copilot/skills/copilot-memory/SKILL.md`
+- installs `~/.copilot/skills/copilot-memory/MEMORY_ROUTING.md`
 - if an existing VS Code `settings.json` is not strict JSON, the installer leaves it unchanged and prints a manual follow-up warning instead of overwriting it
 - on Linux/macOS, automatic VS Code settings updates require `python3`
 
+## Repository instructions
+
+- The repo ships [`.github/copilot-instructions.md`](/lump/apps/copilot-memory-mcp/.github/copilot-instructions.md) for GitHub Copilot repo instructions.
+- The repo ships [`AGENTS.md`](/lump/apps/copilot-memory-mcp/AGENTS.md) for agent routing.
+- The shared reference lives in [`docs/instructions/memory-routing.md`](/lump/apps/copilot-memory-mcp/docs/instructions/memory-routing.md).
+- If you want the same guidance in another repo or user-level instruction file, copy from that shared reference instead of rewriting it from scratch.
+
 ## Release automation
 
 After pushes to `main`, packaged artifacts are built and published as GitHub Release assets for:

docs/instructions/memory-routing.md

@@ -0,0 +1,53 @@
+# Memory Routing Reference
+
+This file is the shared reference for instruction surfaces across the repo and installer package.
+
+## Recommended Order
+
+1. `codebase-memory-mcp` for structural discovery.
+2. `Copilot` repo instructions for repo-wide reminders.
+3. `CLAUDE.md` or `AGENTS.md` for agent-specific routing.
+4. `search_code` or grep only when the question is literal text, config, or a non-code file.
+
+## Structural Questions
+
+Use graph tools first when the question is any of:
+
+- who calls this
+- what does this call
+- what changed because of this diff
+- what services or subsystems exist
+- what should I read first in this repo
+- what code is dead or highly connected
+
+Preferred tools:
+
+- `list_projects`
+- `get_architecture`
+- `search_graph`
+- `trace_path`
+- `detect_changes`
+- `query_graph`
+- `get_code_snippet`
+
+## Operational Questions
+
+Use the lower-level tools when the task is operational:
+
+- `index_repository` and `index_status` for indexing and health
+- `delete_project` for cleanup
+- `manage_adr` for persistent architectural decisions
+- `ingest_traces` for runtime evidence
+
+## What To Ship
+
+- `.github/copilot-instructions.md` for GitHub Copilot repo instructions
+- `AGENTS.md` for agent-level routing in this repo
+- `CLAUDE.md` for Claude-style repo guidance
+- the Copilot skill for tool inventory and examples
+
+## Recommendation
+
+- Keep one skill, not many, unless the skill becomes hard to maintain.
+- Add routing reminders to instructions files instead of creating a new agent system.
+

docs/security/encryption-options.md

@@ -0,0 +1,65 @@
+# Storage Encryption Options
+
+This note records the current at-rest storage situation for `copilot-memory-mcp` and the realistic options if we want encrypted data later.
+
+## Current Reality
+
+- Project databases are plain SQLite files stored under the cache directory, usually `<cache>/<project>.db`.
+- The store layer opens them directly with SQLite file APIs in [src/store/store.c](/lump/apps/copilot-memory-mcp/src/store/store.c).
+- MCP auth is request-level bearer auth, not storage encryption, in [src/auth/auth.c](/lump/apps/copilot-memory-mcp/src/auth/auth.c) and [src/mcp/mcp.c](/lump/apps/copilot-memory-mcp/src/mcp/mcp.c).
+- Session handling in [src/mcp/mcp.c](/lump/apps/copilot-memory-mcp/src/mcp/mcp.c) is project detection and auto-indexing, not an unlock flow.
+- Artifact export/import code writes temp database files and compressed artifacts, which means any encryption scheme must cover more than just the primary `.db`.
+
+## What Encryption Could Mean
+
+### 1. Full-disk encryption
+
+- Lowest effort.
+- Protects against stolen disks and offline access.
+- Does not protect data from a process that already has access to the host.
+- Does not change the app code.
+
+### 2. Encrypted SQLite at the application layer
+
+- Best fit if we want the database itself unreadable without a key.
+- Likely means SQLCipher or a similar SQLite encryption build.
+- Unlock once at startup or first connect, then keep the key in memory for the process lifetime.
+- A session id can help usability, but it is only a bearer secret unless it is tightly bound and short-lived.
+
+### 3. Switch database engines
+
+- Usually not worth it if the only goal is encryption.
+- A different engine does not remove key management, temp-file handling, WAL concerns, backups, or unlock flow design.
+- Only makes sense if we also want different concurrency or deployment properties.
+
+### 4. Field-level encryption
+
+- Poor fit for a graph/search index.
+- Most data must be readable at query time, so this tends to recreate a lot of the storage layer in a more awkward form.
+
+## Critical Gaps To Account For
+
+- WAL and SHM files must not leak plaintext.
+- Temp files created during import/export must not leak plaintext.
+- Backup and artifact paths must be audited separately from the main DB open path.
+- The key must not live in config files, shell history, logs, or persistent env vars if the intent is real secrecy.
+- Once unlocked, plaintext will exist in memory, so host compromise is still out of scope unless we add OS isolation.
+
+## Practical Options
+
+- If the real threat is offline disk theft, use full-disk encryption and keep the app simple.
+- If the real threat is someone reading the cache directory, use encrypted SQLite and an unlock flow.
+- If the real threat is an untrusted local process, encryption alone is not enough; keep bearer auth, ACLs, and host isolation in place.
+
+## Recommendation
+
+- Do not switch database engines just to “get encryption”.
+- Prefer encrypted SQLite if we want the store unreadable at rest.
+- Treat any future session-id unlock as a UX layer on top of key-based encryption, not as the security boundary itself.
+
+## Repo Impact If We Do This Later
+
+- Store open helpers in [src/store/store.c](/lump/apps/copilot-memory-mcp/src/store/store.c) would need an encryption-aware path.
+- Artifact import/export in [src/pipeline/artifact.c](/lump/apps/copilot-memory-mcp/src/pipeline/artifact.c) would need temp-file review.
+- MCP startup/auth in [src/mcp/mcp.c](/lump/apps/copilot-memory-mcp/src/mcp/mcp.c) would need an unlock handshake design if we want first-connect key entry.
+