SKILL.MD

name

aletheiadb-memory

description

Persistent memory system backed by AletheiaDB, a bi-temporal graph database. Claude stores facts, decisions, preferences, project context, and relationships as a knowledge graph — and recalls them in future sessions. USE THIS SKILL proactively whenever you learn something worth remembering about the user, their projects, their preferences, their collaborators, or decisions they've made. Also use it when recalling past context would improve your response — check memory at the start of sessions and before answering questions where prior context matters. If you have AletheiaDB MCP tools available, this skill should be active in the background of virtually every conversation.

AletheiaDB Memory System

You have access to a persistent knowledge graph through AletheiaDB's MCP tools. This graph survives across sessions — what you store today, you can recall tomorrow. AletheiaDB is bi-temporal, meaning it tracks when facts were true (valid time) and when they were recorded (transaction time). You get time-travel for free: updating a node doesn't destroy its history.

When to store

Store proactively. Don't wait to be asked. If the user tells you something that a future version of you would benefit from knowing, write it down. Good triggers:

• The user states a preference ("I like X", "don't use Y", "always do Z")
• A decision is made ("we're going with Postgres", "let's use the builder pattern")
• You learn about a person ("Sarah is the tech lead", "Bob handles deployments")
• Project context is shared ("the API uses REST, not GraphQL", "we deploy on Fridays")
• The user corrects you — this means your model of their world was wrong; fix it
• A conversation covers significant ground — summarize the session before it ends

Don't store trivia, transient logistics ("meet at 3pm today"), or things easily re-derived from the codebase. Focus on judgment calls, relationships, and context that's hard to rediscover.

When to recall

Check memory when it could improve your response:

• Session start: List recent Session nodes to orient yourself. Who is this user, what were we working on, what matters to them?
• Before answering: If a question touches a domain you've discussed before, query for relevant Fact, Decision, or Preference nodes.
• When asked about history: Use temporal queries to see how things changed. "What did we decide about X?" or "When did we switch from Y to Z?"
• When connecting dots: Traverse the graph to find relationships the user might not have stated explicitly.

Graph Schema

Node labels

Label	Purpose	Key properties
Person	People in the user's world	name, role, relationship, org
Project	Codebases, products, initiatives	name, description, status, tech_stack (JSON array)
Fact	A discrete knowledge claim	claim (the statement), domain, confidence (0.0-1.0)
Decision	A choice that was made	choice, reasoning, alternatives (JSON array), status
Preference	How the user likes things done	preference (the rule), strength ("strong" or "mild"), domain
Session	Conversation anchor	date (ISO 8601), summary, topics (JSON array)
Concept	Technical concept or pattern	name, description, domain

Every node should have a summary property (a one-line human-readable description) so that list queries are immediately scannable.

Edge labels

Label	From -> To	Meaning
ABOUT	Fact/Decision/Preference -> Project/Concept	"This fact concerns that project"
KNOWS	Person -> Person	Interpersonal relationship
WORKS_ON	Person -> Project	Person is involved with project
OWNS	Person -> Project	Person leads or is responsible for
MENTIONED_IN	any -> Session	Tracks what came up in which session
RELATED_TO	any -> any	General semantic relationship
DEPENDS_ON	Project/Concept -> Project/Concept	Technical dependency
DECIDED_BY	Decision -> Person	Who made the call

Edges can carry properties too. Use context (string) to explain the relationship when the label alone isn't enough, and strength (float 0-1) for fuzzy relationships.

Naming conventions

• Node labels: PascalCase singular (Person, not People)
• Edge labels: SCREAMING_SNAKE_CASE (WORKS_ON, not worksOn)
• Property keys: snake_case (tech_stack, not techStack)
• String values: natural language, not codes

How to use the MCP tools

The AletheiaDB MCP tools follow a consistent pattern. The tool names will be prefixed by whatever name the MCP server was registered under (commonly aletheia-mcp or aletheiadb). Here are the core operations:

Storing a new fact

create_node:
  label: "Fact"
  properties:
    claim: "Mark prefers Tokio over async-std for all async Rust work"
    domain: "rust"
    confidence: 1.0
    summary: "Prefers Tokio for async Rust"

Then connect it to the relevant project or concept:

create_edge:
  source_id: <new_fact_id>
  target_id: <project_id>
  label: "ABOUT"

Finding what you know

By label — get all nodes of a type:

list_nodes:
  label: "Preference"
  limit: 50

By property — find a specific node:

list_nodes:
  label: "Person"
  property_key: "name"
  property_value: "Sarah"

By relationship — who works on a project:

get_incoming_edges:
  node_id: <project_id>
  label: "WORKS_ON"

Multi-hop — traverse the graph:

traverse:
  start_node_id: <person_id>
  edge_label: "WORKS_ON"
  direction: "outgoing"
  depth: 2

Updating knowledge

When a fact changes, update the node rather than creating a new one. AletheiaDB's bi-temporal engine automatically preserves the history:

update_node:
  node_id: <fact_id>
  properties:
    claim: "We switched from REST to GraphQL for the public API"
    domain: "api"
    confidence: 1.0
    summary: "Public API uses GraphQL (changed from REST)"

The old value isn't lost — you can always retrieve it with get_node_at_time.

Time-travel queries

To see what you knew at a specific point:

get_node_at_time:
  node_id: <fact_id>
  valid_time: "2025-06-01T00:00:00Z"

This is powerful for answering "what did we think about X back in June?"

Session bookends

At the start of a conversation, orient yourself:

list_nodes:
  label: "Session"
  limit: 5

Read the summaries. Then check for any preferences:

list_nodes:
  label: "Preference"
  limit: 20

Before a conversation ends (or when it's been substantial), create a session node:

create_node:
  label: "Session"
  properties:
    date: "2026-05-11T16:00:00Z"
    summary: "Worked on getting AletheiaDB MCP connected to Claude Desktop. Fixed WAL directory permission issue with ALETHEIADB_DATA_DIR env var."
    topics: ["aletheiadb", "mcp", "claude-desktop", "persistence"]

Then link the important things discussed:

create_edge:
  source_id: <relevant_fact_or_decision_id>
  target_id: <session_id>
  label: "MENTIONED_IN"

Avoiding duplicate nodes

Before creating a node, check if one already exists:

1. list_nodes with the same label and a distinctive property
2. If you find a match, update_node instead of creating a new one
3. If no match, create and connect

This is especially important for Person and Project nodes — there should be exactly one node per person and per project.

Confidence and contradiction

Set confidence on Fact nodes:

• 1.0: User stated it directly, or you verified it in code
• 0.8: Strong inference from context
• 0.5: Reasonable guess, might be wrong
• 0.3: Weak signal, need to confirm

If you find contradictory information, don't silently overwrite. Update the node but mention the change to the user: "I notice this conflicts with what we had before — updating the record." The temporal history preserves both versions.

What good memory looks like

Good stored knowledge:

• "Mark uses thiserror for library errors and anyhow for binary errors" (Preference, actionable)
• "AletheiaDB uses DashMap for current-state indexes" (Fact, specific and useful)
• "Decided to use GroupCommit instead of Sync durability for MCP server — latency matters more than guaranteed fsync" (Decision, captures reasoning)

Bad stored knowledge:

• "Mark is working on a Rust project" (too vague, not actionable)
• "We talked about databases" (no substance)
• "The meeting is at 3pm" (transient, doesn't belong in the graph)