Knowledge Graph — Relationships Between Facts

Yukkai's Knowledge Graph is the connective tissue between memory facts. While the HumanMemory system stores individual facts across five layers (identity, preferences, patterns, projects, episodic), the Knowledge Graph maps how those facts relate to each other — enabling deeper reasoning and more intelligent assistance.

What Is a Knowledge Graph?

A knowledge graph is a network of entities (nodes) and their relationships (edges). In Yukkai's case:

• Nodes are memory facts: your name, your preferred language, your current project, a decision you made yesterday.
• Edges are the relationships between them: "works on", "prefers over", "is part of", "was decided during", "conflicts with".

This structure lets Yukkai go beyond simple fact retrieval and perform relational reasoning — answering questions that require connecting dots across different memory layers.

How It Works

Fact Linking

When Yukkai learns a new fact, it doesn't just store it in isolation. The Knowledge Graph:

1. Identifies related facts — Scans existing memory for facts that reference the same entities, projects, or concepts.
2. Creates edges — Establishes typed relationships between the new fact and existing ones.
3. Updates confidence — If multiple facts reinforce each other, their confidence scores may increase.

Relationship Types

Relationship	Meaning	Example
works_on	User is actively engaged with	You → "MyApp" project
prefers	User favors one option over another	You prefer Swift over Objective-C
part_of	One entity belongs to another	"AuthController" is part of "MyApp"
learned_during	A fact was acquired in a specific context	Preference for MongoDB learned during "MyApp" project
supersedes	A newer fact replaces an older one	PostgreSQL now supersedes MongoDB
conflicts_with	Two facts are contradictory	"Likes dark mode" conflicts with observed light-mode usage
related_to	General association	"FastAPI" related_to "Python"

Cross-Layer Reasoning

The Knowledge Graph's power comes from its ability to connect facts across different memory layers:

Example scenario:

1. Identity: You're a backend developer
2. Preferences: You prefer Python and FastAPI
3. Projects: You're working on "MyApp" with a REST API
4. Episodic: Yesterday you decided to add authentication

The Knowledge Graph connects these: You (developer) → prefers (Python, FastAPI) → working on (MyApp) → needs (authentication). When you ask "How should I implement auth for MyApp?", Yukkai doesn't just retrieve individual facts — it traverses the graph to build a complete picture and recommends FastAPI-native solutions (like OAuth2 with fastapi.security).

Conflict Detection

When the Knowledge Graph detects a conflicts_with relationship — two facts that contradict each other — Yukkai can:

1. Surface the conflict — "I noticed you said you prefer tabs, but I've observed you using spaces recently. Which should I follow?"
2. Prioritize by source — Explicitly stated facts have higher confidence than observed or inferred ones.
3. Track evolution — When a new fact supersedes an old one (e.g., you switched from MongoDB to PostgreSQL), the graph maintains the history so Yukkai understands the change happened, rather than just forgetting the old preference.

Benefits Over Flat Memory

Flat Memory	Knowledge Graph
Stores facts independently	Connects facts with typed relationships
Retrieval is keyword-based	Retrieval can traverse relationship paths
Cannot detect contradictions	Detects and resolves conflicts
No context about how facts were learned	Preserves the context in which each fact was acquired
Cannot reason across layers	Enables cross-layer relational reasoning

Privacy and Security

The Knowledge Graph is stored entirely on your device, protected by the same encryption as the rest of HumanMemory:

• AES-256-GCM encryption for stored data
• No external transmission — the graph never leaves your Mac (except via YukkaiBridge to your own iPhone)
• Full user control — you can view, edit, or sever any relationship in the graph

Future Directions

The Knowledge Graph is designed to grow smarter over time. As Yukkai learns more about you, the graph becomes denser and richer — enabling increasingly nuanced understanding of your work habits, preferences, and project contexts. Future enhancements include:

• Automatic fact promotion — Moving observed patterns from episodic to preferences when confidence is high enough
• Graph-based predictions — Using the graph structure to predict what you'll need before you ask
• Temporal reasoning — Understanding how your preferences and projects evolve over time