Knowledge Graph

Knowledge Graph Skill

Maintain a lightweight, append-only entity graph that compounds durable facts across sessions.

When to Use

• Extract durable facts from recent work or conversation history
• Rewrite entity summaries from active facts
• Answer "what do we know about X?" without reopening large transcripts
• Keep shared context for people, companies, and projects inside the workspace

Data Model

Store the graph under:

<workspace>/life/areas/
  people/<slug>/
  companies/<slug>/
  projects/<slug>/

Each entity folder should contain:

• summary.md for the short, current snapshot
• facts.jsonl for atomic, append-only facts

Use one JSON object per line:

{
  "id": "<slug>-NNN",
  "fact": "Plain-English fact",
  "category": "relationship|milestone|status|preference|context|decision",
  "ts": "YYYY-MM-DD",
  "source": "conversation|manual|inference",
  "status": "active|superseded",
  "supersedes": "<older-id>"
}

Fact Rules

• Keep facts atomic. One durable fact per entry.
• Append new facts instead of rewriting history.
• When something changes, add a new fact and mark the old one as superseded.
• Skip ephemera, greetings, speculation, and low-value chatter.
• Check existing facts before adding duplicates.

Durable facts usually include:

• role or relationship changes
• key decisions
• long-lived preferences
• major project milestones
• stable operating context

Workflows

Fact Extraction

• Read the recent daily note and the recent conversation window.
• Identify durable facts worth preserving.
• Resolve entity type and slug.
• Create the entity folder if it does not exist.
• Append new facts to facts.jsonl.
• Note extraction activity in the daily note if the workspace uses one.

Weekly Synthesis

• List entities changed during the week.
• Load active facts only.
• Rewrite summary.md in 3 to 8 concise lines.
• Ensure contradicted facts are marked superseded.
• Record a short synthesis note in the daily log if applicable.

Entity Lookup

• Read summary.md first.
• Open facts.jsonl only if the summary is stale or the user asked for detail.
• Fall back to broader memory search only when the entity is missing from the graph.

Low-Token Recall

Recall should be triggered, not automatic.

• Recall when the user names a tracked person, company, or project.
• Recall when the user explicitly asks to remember, recall, or summarize prior context.
• Inject only the short summary by default.
• Avoid loading raw facts unless the user asked for specifics or contradictions need resolution.

Setup

Create the core directories once:

mkdir -p life/areas/people life/areas/companies life/areas/projects

If multiple agents share one workspace, point them at the same life/ directory so they operate on the same entity store.

Safety Boundaries

• Do not store sensitive secrets, credentials, or highly personal data unless the user explicitly asked for it.
• Do not create entities or facts for casual chat that has no durable value.
• Do not inject the graph into every conversation by default.
• Do not delete historical facts; supersede them with a newer fact instead.