Personal vs. Project

"Where should this knowledge live — in my project or my personal graph?"

Every knowledge graph belongs to one of two scopes: project or personal.

Project KG

A project KG lives inside a project's directory at ./knowledge/. It contains knowledge specific to that project:

• Bug fixes and workarounds found in this codebase
• Architecture decisions for this system
• Debugging sessions for this project's stack

Best for: Anything that only makes sense in the context of one project.

Personal KG

A personal KG lives at ~/.kmgraph/ and is accessible from any project. It contains cross-project patterns and lessons:

• Workflow habits ("Create vs Update in implementation plans")
• Tool quirks that appear across projects (MCP registration, IDE setup)
• Personal ADRs ("Why I prefer TypeScript strict mode")
• Reusable checklists and process patterns

Best for: Knowledge that would apply identically in your next project.

Identity and rules files

Each scope also scaffolds two special files:

File	Scope	Committed?	Purpose
knowledge/rules.md	Project	Yes	Project conventions shared by all contributors
knowledge/me.md	Project	No — gitignored	Who you are in this project (per-contributor)
~/.kmgraph/rules.md	Personal	N/A local	Cross-project behavioral rules
~/.kmgraph/me.md	Personal	N/A local	Cross-project personal identity and preferences

These files are the platform-agnostic foundation that all AI platform config files (CLAUDE.md, .cursorrules, etc.) point to. See Your AI Profile for the full setup guide.

How they work together

Behavior	Detail
/kmgraph:kmg-recall	Searches both KGs automatically when a personal KG is registered. Results show [project] or [personal] source labels.
/kmgraph:kmg-capture-lesson	Shows a KG picker when ≥2 KGs are registered. Only one prompt per session (choice remembered).
SessionStart hook	Surfaces recent personal KG lessons alongside project lessons.
Target KG	Resolved from the current working directory for every call — no global "active" pointer to keep in sync. Running from inside a project directory targets that project's KG by default; see [personal]/[project] markers below to reach the other scope without changing directories.

When to use personal vs project

Situation	Save to
"I fixed a bug specific to this repo"	Project KG
"I learned a general debugging pattern"	Personal KG
"We decided to use Redis for this project"	Project KG
"I always prefer feature flags over config files"	Personal KG
"This MCP registration quirk affects all IDEs"	Personal KG

Scope diagram

Routing captures by level

All capture commands (session-summary, create-adr, capture-lesson, sync-all) and recall accept an explicit routing flag — or recognize equivalent natural language in the invocation message:

Signal	Resolves to	Behavior
--user / "user level" / "for the user"	Personal KG (~/.kmgraph/)	Writes directly; bypasses cwd resolution entirely
--project / "for this project" / "project level"	Current project's KG	Resolves the project KG for the current directory; no directory change needed
--named=<kg> / name of a KG (e.g., "career-ops")	Named KG from kg-config.json	Writes to named KG directly, by name, regardless of cwd
(no signal)	The KG resolved from the current working directory	Default behavior; every draft shows Saving to: {path} for confirmation

Examples:

/kmgraph:kmg-capture-lesson "user level"        # → ~/.kmgraph/lessons-learned/
/kmgraph:kmg-create-adr --project               # → current project's knowledge/decisions/
/kmgraph:kmg-session-summary --named=career-ops # → career-ops KG sessions/
/kmgraph:kmg-recall "auth patterns" --user      # → search only ~/.kmgraph/

If a named KG isn't found, a fuzzy suggestion prompt appears. If the project has no configured KG, a setup prompt offers options to initialize or redirect the capture.

[personal]/[project] markers in search and capture

kg_search and kg_capture recognize a one-time scope override written directly at the start of the query or content text: a literal [personal] or [project] prefix.

[personal] what did I note about feature-flag preferences?
[project] search for the auth timeout fix

Only the exact bracketed literal at the very start of the string is recognized — the parser is intentionally strict:

• Case-sensitive, brackets required: [personal] matches, personal (bare word) and [Personal] do not
• Only at the start of the string — a marker appearing mid-sentence is left as ordinary text
• Not recognized as a flag or slash-command style: --personal ... and /personal ... are not markers

The marker is stripped from the text before it's used as the search query or capture content, and it only affects the single call it's attached to — a marker on one kg_search call does not change where the next call resolves. This scope override is interactive-mode only: automated/scripted calls (see KMG_INPUT_REQUIRED) ignore any bracketed prefix and always resolve from cwd/explicit parameters, so an untrusted string can't silently redirect a scripted call to the personal KG.

The first time a marker (or scope: "user") reaches the personal KG from a repository the session hasn't touched before, a one-time confirmation is required before the personal KG is read or written — this is a distinct, per-repository confirmation, separate from the marker parsing itself, and exists to stop a crafted instruction embedded in a freshly-cloned untrusted repo from silently reaching the personal KG.

Setup

• During init: /kmgraph:kmg-init offers to create a personal KG at the end of setup
• Standalone: /kmgraph:kmg-init-personal-kg creates and registers the personal KG at any time

See Multi-KG Workflows for advanced configuration and Your AI Profile for setting up me.md and rules.md.

Related

• Graph Configuration — categories, storage paths, and kg-config.json
• Multi-KG Workflows — managing multiple graphs side by side
• Your AI Profile — setting up me.md and rules.md