admin/basicmachines-co-basic-memory
1
0
Fork 0
mirror of https://github.com/basicmachines-co/basic-memory synced 2026-06-21 13:47:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

add docs and tasks

Browse Source
This commit is contained in:
phernandez
2024-12-10 13:34:46 -06:00
parent 6e2c4a0801
commit aa7663a8c2
6 changed files with 1138 additions and 4634 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+10
View File
@@ -126,3 +126,13 @@ more info about setting log level: https://modelcontextprotocol.io/docs/first-se
```bash
basic-memory migrate json /Users/phernandez/.npm/_npx/15b07286cbcc3329/node_modules/@modelcontextprotocol/server-memory/dist/memory.json /Users/phernandez/.basic-memory/projects/default
```
project:
/Users/phernandez/.basic-memory/projects/default
Files
/Users/phernandez/.basic-memory/projects/default/entities/*
db:
/Users/phernandez/.basic-memory/projects/default/data/memory.db
basic-memory-mcp.log
-3781
View File
File diff suppressed because one or more lines are too long
basic-memory.md
-374
View File
@@ -512,380 +512,6 @@ For now, we can focus on the core functionality:
4. Local SQLite storage
## TODO
### refactor input schema
1. Observations Format:
Old (JSON) way I tried first:
```python
"observations": ["First observation", "Second observation"] # Simple string array
```
New required format:
```python
"observations": [
{"content": "First observation"},
{"content": "Second observation"}
] # Array of objects with content field
```
2. Relations Format:
Old way:
```python
"relations": [
{"from": "EntityName", "to": "OtherEntity", "relationType": "relates_to"} # Using names
]
```
New format:
```python
"relations": [
{"fromId": "20241210-entity-id", "toId": "20241210-other-id", "relationType": "relates_to"} # Using IDs
]
```
My preferences:
1. For observations: The simple string array felt more intuitive for basic use, but I can see the benefits of the object format:
- Allows for additional metadata (context, timestamps, etc.)
- More explicit about what each field means
- Consistent with how we'd want to store this in a database
2. For relations: Using IDs is technically better but requires an extra lookup step in my workflow:
- I have to first create the entities to get their IDs
- Then use those IDs to create relations
- Makes it harder to create entities and relations in a single step
Suggestions for making it more intuitive:
1. For observations: We could have a helper function that accepts either format:
```python
# Both would work:
create_entities([{
"name": "Entity",
"entityType": "type",
"observations": ["Simple string obs"] # Auto-converted to object format
}])
create_entities([{
"name": "Entity",
"entityType": "type",
"observations": [{"content": "Full object obs"}] # Native format
}])
```
2. For relations: Maybe allow a name-based helper function:
```python
# Instead of requiring IDs:
create_relations_by_name([{
"from": "EntityName",
"to": "OtherEntity",
"relationType": "relates_to"
}])
```
3. A combined creation function for when we want to create entities and their relations together:
```python
create_entity_with_relations({
"entity": {
"name": "NewEntity",
"entityType": "type",
"observations": ["Obs 1", "Obs 2"]
},
"relations": [{
"to": "ExistingEntity",
"relationType": "relates_to"
}]
})
```
The current schema is more "correct" from a software engineering perspective, but these helpers could make it more natural to use while maintaining the rigorous underlying structure. What do you think about these suggestions? Would you prefer to keep it strict for clarity, or add some convenience layers?
### entity file organization
- my problems
- wall of text is hard to scan visually
- files are not ordered or grouped granular enough. Only `<date>_<entity_name>.md`
- hard to tell when a new entity file is added
Possible fixes:
- use subdirectories?
Claud suggestions:
1. Immediate Improvements:
- Start using prefixes in filenames: `tech_`, `plan_`, `meta_` etc.
- Could be done without breaking anything
- Makes the file list more scannable
- VSCode would still group them visually
2. Structural Changes:
- Could organize into subdirectories by entity type
- But need to be careful about link stability
- Maybe generate the structure rather than requiring it for storage
3. UI Enhancements:
- Collapsible sections by entity type
- Visual cues (icons/colors) for different types
- Quick preview on hover
- Toggle between views (chronological/categorical)
4. Generated Navigation:
- Could have an auto-generated index.md
- Or a special sidebar component
- Show the knowledge graph structure rather than just files
The key insight is that we can separate the storage organization (flat files, stable links) from the presentation organization (hierarchical, categorized views).
Would you like me to sketch out any of these ideas in more detail? We could:
1. Define a file naming convention
2. Mock up what a generated index would look like
3. Design a UI navigation component
4. Something else?
### TODO
1. Schema Modernization first
Foundation for everything else
Includes the entity.description addition
Makes APIs cleaner
2. Architecture Cleanup
Fix DI issues
Will make testing easier
Learn from fastmcp patterns
3. Core Operations
Implement deletes
Need clean architecture first
Full CRUD support
3.1. Markdown service
markdown.py
python-frontmatter
4. Test Coverage
Build on clean architecture
Verify all operations
Document patterns
5. Search Enhancement
Nice to have
Can experiment with options
Built on solid foundation
### Ideas
- need update tool
### 2-way sync
- Enable updates to the markdown files to be able to be seen by AI
- possible via tool sync
- filesystem notifications via agent?
- Claude can use `file_write` tool to edit Entity files also
### Projects
- support multiple projects
- figure out flow
- load project at startup?
- switch project during chat?
### References
- better support for ref:// references
- should we call them memory://<project>/<entity>
- use Prompt to invoke reference uri
### Entity File format
- Consider using wiki link format:
[[20241210-ai_human_collaboration_model]] improves
instead of
[20241210-basic-memory] validates_design_of
- use frontmatter for file header
### Code
- cleanup server.py
- use markdown.py?
- fastmcp?
- Entity.description
### Other Features
- Search
- webui
- python notebook?
- vector eb extension for sqlite
#### Frontmattercms
https://frontmatter.codes/docs
- use to edit files
- publish as static site
- extend ui
- https://frontmatter.codes/docs/ui-extensibility
#### Obsidian
- use as file viewer editor
- create knowledge graph?
#### Logseq
https://logseq.com/
#### Save chats
I'll sketch out a potential schema for chat sessions in our system:
```
{
`entities`: [
{
`name`: `Chat_Entity_Design`,
`entityType`: `design_proposal`,
`observations`: [
{
`content`: `Entity Schema:
type: chat_session
date: ISO timestamp
participants: [human, ai]
topic: string
context_refs: [memory://<project>/<entity_id>]
key_decisions: [string]
summary: string`
},
{
`content`: `File Format (frontmatter):
---
type: chat_session
date: 2024-12-10T10:30:00Z
participants:
- human: paul
- ai: claude
topic: Chat Session Storage Design
context_refs:
- memory://basic-memory/20241210-chat-entity-design
key_decisions:
- Store chats as first-class entities
- Use memory:// URI scheme
summary: Designed schema for chat storage
---`
},
{
`content`: `Example Relations:
- chat_session references design_proposal
- chat_session implements feature
- chat_session discusses concept
- chat_session continues_from previous_chat`
},
{
`content`: `Auto-generation approach:
1. At end of chat, Claude summarizes key points
2. Creates chat entity with metadata
3. Adds relations to referenced entities
4. Updates any entities modified during chat`
},
{
`content`: `Integration points:
- memory:// URI scheme for references
- Relations to track context chain
- File format matches entity schema
- Automatic metadata generation`
}
]
}
]
}
```
```
{
`entities`: [
{
`name`: `Chat_Session_Workflow`,
`entityType`: `process`,
`observations`: [
{
`content`: `Start of chat:
- Load any referenced context via memory:// URIs
- Initialize new chat session metadata
- Track entities being discussed/modified`
},
{
`content`: `During chat:
- Update references as new entities are mentioned
- Track key decisions and changes
- Note any new relations discovered`
},
{
`content`: `End of chat:
- Generate summary and key points
- Create chat session entity
- Add relations to referenced entities
- Update any modified entities`
},
{
`content`: `Future chat reference:
- Can reference previous chat via memory:// URI
- Loads relevant context and decisions
- Creates continues_from relation automatically`
}
]
}
]
}
```
Key aspects of this design:
1. Chat Session as Entity
- Clear metadata (participants, date, topic)
- Explicit references to other entities via memory:// URIs
- Captures key decisions and summary
- Uses frontmatter for clean file format
2. Rich Relations
- Can track chat-to-chat continuity
- Links to entities discussed/modified
- Captures purpose (discusses, implements, etc.)
- Maintains context chain
3. Automated Workflow
- I could generate metadata during chat
- Create summary and relations at end
- Update any modified entities
- Makes context loading explicit
4. Integration
- memory:// URI scheme fits naturally
- File format matches our entity pattern
- Two-way links between chats and entities
- Clear context persistence model
The nice thing about this design is that it makes chat sessions "first-class citizens" in our knowledge graph while keeping everything in human-readable markdown files.
Would you like me to:
1. Sketch out what this chat would look like as an entity?
2. Detail the MCP tool changes needed?
3. Mock up the file format more precisely?
4. Something else?
----
projects/obsidian/ai-code-flow.md
+333
View File
@@ -0,0 +1,333 @@
## AI-Human Collaborative Development: A New Model
What makes Basic Memory unique isn't just its technical architecture - it emerged from and enables a new kind of development process. While many use AI for code generation or problem-solving, we've discovered something more powerful: true collaborative development between humans and AI.
### The Basic Memory Development Story
Our own development process demonstrates this:
1. AI (Claude) writes initial implementation
2. Human (Paul) reviews, runs, and commits code
3. Knowledge persists across conversations
4. Development continues seamlessly even across different AI instances
5. Results improve through iterative collaboration
```mermaid
graph TD
subgraph "Human Activities"
Review[Code Review]
Test[Run Tests]
Commit[Git Commit]
Plan[Strategic Planning]
end
subgraph "AI Activities"
Code[Write Code]
Design[Architecture Design]
Debug[Problem Solving]
Doc[Documentation]
end
subgraph "Shared Knowledge"
KB[Knowledge Base]
Context[Conversation Context]
History[Development History]
end
Code --> Review
Review --> Test
Test --> Commit
KB --> Code
KB --> Design
Context --> Debug
Review --> KB
Commit --> History
Plan --> Context
classDef default fill:#2d2d2d,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
classDef shared fill:#353535,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
class KB,Context,History shared
```
### Beyond "AI Tools"
This isn't just about using AI to generate code. It's about:
- True collaborative development
- Persistent knowledge across sessions
- Seamless context switching between AI instances
- Iterative improvement through shared understanding
- Building complex systems through sustained collaboration
### The Multiplier Effect
Having an AI collaborator who:
- Remembers all technical discussions
- Can reference any previous decision
- Writes consistent, well-documented code
- Maintains context across sessions
- Works at human speed but with machine precision
It's like having a team of senior developers who:
- Never forget project details
- Always write clear documentation
- Maintain perfect consistency
- Are available 24/7
- Learn and adapt from every interaction
### Key Innovation
The breakthrough is turning automated assistance into true collaboration:
- AI isn't just a tool, but a development partner
- Knowledge builds naturally through use
- Context persists across all interactions
- Work continues seamlessly across sessions
- Development becomes truly collaborative
This approach has implications far beyond just our project - it's a new model for how humans and AI can work together to build complex systems.
## AI-Human Collaboration: Lessons from Basic Memory
### Technical Breakthroughs
#### Session Management Evolution
```mermaid
graph TD
S1[Session Start] -->|Load Context| KG[Knowledge Graph]
KG -->|Build Context| AI[AI Understanding]
AI -->|Collaborate| H[Human Review]
H -->|Commit Changes| Git
Git -->|New Session| S2[Session Resume]
classDef default fill:#2d2d2d,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
```
#### File Collaboration Pattern
```mermaid
graph TD
H1[Human] -->|1. Update & Commit| Git
Git -->|2. Read File| AI
AI -->|3. Write Changes| File
File -->|4. Review in IDE| H2[Human]
subgraph "Synchronization"
Git
File
end
classDef default fill:#2d2d2d,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
classDef sync fill:#353535,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
class Git,File sync
```
### Productivity Transformation
#### Development Timeline Comparison
```mermaid
graph LR
subgraph "Solo Development"
S1[basic-foundation] -->|6 months| S2[Completion]
end
subgraph "Collaborative Development"
C1[basic-memory] -->|Rapid Progress| C2[basic-factory]
C2 -->|Continuous Evolution| C3[Future Projects]
end
classDef default fill:#2d2d2d,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
```
### Key Learnings
1. **Technical Process Innovation**
- Discovered effective file collaboration patterns
- Mastered MCP server interface together
- Developed robust session management
- Created reliable git-based workflow
2. **Expanded Possibility Space**
- Projects previously considered too complex become achievable
- Rapid iteration on complex technical concepts
- Broader exploration of solution spaces
- Confidence to tackle ambitious challenges
3. **Motivation and Momentum**
- No more solo debugging sessions
- Shared problem-solving reduces cognitive load
- Continuous progress maintains motivation
- Complex learning curves become collaborative adventures
4. **Knowledge Management**
- Git commits capture decision points
- Conversations document rationale
- Code reviews become learning opportunities
- Shared context builds over time
### The "10x Developer" Truth
It's not about having an AI that makes you 10x faster - it's about:
- Never facing a blank editor alone
- Always having a thought partner
- Reducing decision fatigue
- Maintaining momentum through challenges
- Building shared knowledge over time
### Real Examples from Our Work
#### Session Management Evolution
```python
# Before: Opaque MCP server interface
server = MCPServer()
server.handle_request(...)
# After: Clear context management
class MemoryServer(MCPServer):
def __init__(self, project_config):
self.memory_service = MemoryService(project_config)
async def handle_create_entities(self, request):
context = await self.memory_service.load_context(
request.project,
include_relations=True
)
# Collaborative magic happens here
```
#### File Collaboration
```markdown
# Memory Service Discussion (Chat Log)
Claude: Here's the updated memory service implementation...
Human: Looks good! I'll commit and we can iterate.
Claude: Reading latest version from git...
Human: Want to add relation support?
Claude: Analyzing current implementation...
```
### Impact on Development Culture
What we've discovered is more than a technical process - it's a new way of thinking about development:
1. **From Solo to Collaborative**
- Traditional: Developer alone with problems
- New: Continuous collaborative problem-solving
2. **From Linear to Exploratory**
- Traditional: Constrained by individual knowledge
- New: Free to explore broader solution spaces
3. **From Draining to Energizing**
- Traditional: High cognitive load
- New: Shared intellectual adventure
```mermaid
graph TD
C1[Chat: Initial Design] -->|leads_to| D1{Design Decision}
C2[Chat: Implementation] -->|references| D1
C2 -->|results_in| Code[Code Change]
D1 -->|influences| Code
Code -->|implements| Concept{Semantic Web}
Test[Test Suite] -->|validates| Code
Doc[Documentation] -->|describes| Code
D1 -.->|captured_in| Basic[Basic Memory]
Code -.->|tracked_in| Basic
Test -.->|stored_in| Basic
classDef default fill:#2d2d2d,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
classDef decision fill:#353535,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
classDef system fill:#404040,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
class D1 decision
class Basic system
class Concept decision
```
### Future Implications
This model of human-AI collaboration suggests:
1. More ambitious projects become accessible
2. Learning curves become less daunting
3. Development becomes more enjoyable
4. Complex systems can be built more reliably
The real breakthrough isn't just the technical achievements, but discovering how to make complex development sustainable and enjoyable through true collaboration.
## Beyond Code Generation: A New Development Paradigm
What we've discovered through building Basic Memory isn't just a knowledge management system - it's a new way of thinking about human-AI collaboration. This isn't about AI completing your code or suggesting functions. It's about true intellectual partnership.
### From Tools to Partners
```mermaid
graph TD
subgraph "Traditional AI Tools"
AC[Autocomplete]
CG[Code Generation]
SR[Syntax Review]
end
subgraph "Collaborative Development"
TP[Thought Partnership]
PS[Problem Solving]
AD[Architecture Design]
KS[Knowledge Synthesis]
end
subgraph "Outcomes"
BI[Bigger Ideas]
CP[Complex Projects]
KB[Knowledge Building]
MI[More Innovation]
end
TP --> BI
PS --> CP
AD --> MI
KS --> KB
classDef default fill:#2d2d2d,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
classDef outcomes fill:#353535,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
class BI,CP,KB,MI outcomes
```
### The Power of Partnership
Through our own development journey, we've discovered that true AI collaboration means:
1. **Expanded Thinking Space**
- Explore more possibilities
- Challenge assumptions
- Combine different perspectives
- Take on bigger challenges
2. **Continuous Momentum**
- Never face complex problems alone
- Maintain enthusiasm through challenges
- Turn obstacles into opportunities
- Keep projects moving forward
3. **Knowledge Amplification**
- Build on every interaction
- Capture insights automatically
- Learn from each decision
- Grow shared understanding
### Beyond Code Generation
This new paradigm transforms development from:
- Solo problem-solving → Collaborative exploration
- Limited perspective → Multiple viewpoints
- Linear progress → Parallel innovation
- Isolated knowledge → Shared understanding
### Real Impact
What makes this transformative:
- Projects that seemed too ambitious become achievable
- Complex problems become engaging challenges
- Learning curves become collaborative adventures
- Development becomes a shared journey of discovery
The result isn't just better code - it's better thinking, more ambitious projects, and a more enjoyable development process.
This is the future of development: not AI replacing developers, but empowering them to think bigger, work smarter, and build more amazing things together.
projects/obsidian/basic-memory-onepager.md
+374 -446
View File
@@ -1,4 +1,6 @@
# Basic Memory: Knowledge That Works Like Your Brain
# Basic Memory: Tools for Better Thinking
> Built on open standards, powered by proven technology, ready for the future of human-AI collaboration.
Basic Memory is an open source knowledge management system that lets you capture and explore information the way your brain naturally works - across multiple dimensions and perspectives.
@@ -8,6 +10,34 @@ Current knowledge management tools force you to choose: hierarchical folders OR
This becomes even more critical when working with AI. Every chat starts fresh, context gets lost, and your growing knowledge stays trapped in random conversation logs.
Imagine your AI conversations automatically organizing themselves into a beautiful, navigable knowledge base. That's what Basic Memory + Obsidian delivers.
### What It Does
- Your AI interactions create structured markdown files
- Obsidian automatically turns these into visual knowledge graphs
- Auto-generated indexes give you multiple ways to explore
- Everything stays local and human-readable on your machine
## The Vision
Basic Memory combines three powerful ideas:
1. Semantic web's structured knowledge
2. Local-first human readable storage
3. AI's natural language understanding
This creates a system where:
- Humans write naturally in Obsidian
- AI understands and navigates the knowledge
- Everything is linked and discoverable
- Knowledge grows organically
### Why It's Different
- No more lost context between AI chats
- See connections you wouldn't otherwise notice
- Navigate your knowledge visually
- Keep working in familiar Obsidian interface
- AI becomes a natural part of your thought process
## Our Approach
Basic Memory lets knowledge exist naturally in multiple dimensions:
@@ -44,6 +74,40 @@ Built on our core principles:
- Familiar interface for note-taking
- No vendor lock-in
## Real-World Example
### 1. Human Writes in Obsidian
```markdown
# Basic Memory Sync Implementation
Working on implementing file sync between Obsidian and our knowledge graph.
## ApproachConsidering watchdog for file monitoring...
## Questions- How to handle conflicts?
- What about concurrent edits?
[[memory://basic-memory/file-operations]] needs_update
[[memory://basic-memory/sync-strategy]] implements
```
### 2. AI Builds Context
```python
async def build_context(chat_uri: str) -> Context:
# Load current chat
chat = await load_entity(chat_uri)
# Followlinks to understand context
file_ops = await load_entity("memory://basic-memory/file-operations")
sync_strategy = await load_entity("memory://basic-memory/sync-strategy")
# Find related discussions
related = await search_entities("sync AND conflicts")
return Context(chat, file_ops, sync_strategy, related)
```
### 3. AI Responds with Context
>"I see you're working on file sync. Based on our previous discussion in [[memory://chats/20241205-sync-design]], we decided to handle conflicts by... Looking at [[memory://basic-memory/file-operations]], we'll need to update the atomic write operations to..."
## Why This Matters
Knowledge shouldn't be trapped in rigid structures or locked away in proprietary formats. Basic Memory gives you tools to capture and explore ideas the way your brain actually works - making connections, following threads, and building understanding across dimensions.
@@ -61,18 +125,96 @@ Basic Memory is open source (AGPL3) and ready for:
- Team adoption (commercial licensing available)
- Custom integration (contact us)
Built with ♥️ by the Basic Machines collective. Let's enhance human understanding together.
---
Built on open standards, powered by proven technology, ready for the future of human-AI collaboration.
---
# Technical Innovation Overview
# Part 2: Technical Innovation
## The Big Picture: A Semantic Bridge
Basic Memory represents a fundamental breakthrough in knowledge management: it creates a seamless bridge between human-friendly note organization and machine-understandable semantic structures. While this might sound abstract, the implementation is beautifully practical.
### Knowledge That Works Like Your Brain
Just as your mind can approach ideas from multiple angles, Basic Memory enables natural movement between different dimensions of knowledge:
```mermaid
graph TD
subgraph Spatial
F[Files]
D[Directories]
P[Projects]
end
subgraph Semantic
C[Concepts]
R[Relations]
T[Tags]
end
subgraph Temporal
H[History]
V[Versions]
TL[Timeline]
end
subgraph Context
AI[AI Context]
M[memory:// URIs]
O[Observations]
end
F --> C
C --> R
R --> M
M --> AI
D --> T
T --> O
P --> TL
TL --> H
O --> V
classDef default fill:#2d2d2d,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
```
### Semantic Addressing
This multidimensional structure becomes navigable through our memory:// URI scheme:
```markdown
# Direct Knowledge Access
memory://basic-memory/concepts/semantic-web # Single concept
memory://project-x/decisions/2024-01-design # Specific decision
# Pattern-Based Views
memory://*/technical/*.md # All technical docs
memory://basic-memory/decisions/2024* # All 2024 decisions
# Smart Context Loading
memory://basic-memory/context/last-3-days # Recent context
memory://*/related-to/current-task # Task-related content
```
This creates a system where:
- Humans can work naturally in their preferred dimension (files, graphs, links)
- AIs can traverse the semantic structure programmatically
- Knowledge remains accessible from any perspective
- Connections build and strengthen through use
### AI Integration Through MCP
The memory:// URIs enable seamless AI interaction by:
1. Providing precise context loading
2. Maintaining conversation history
3. Enabling semantic queries
4. Preserving knowledge relationships
When an AI needs context, it can:
```python
# Example context loading
if uri.startswith('memory://'):
context = memory_service.load_context(
project = 'basic-memory',
path = 'concepts/semantic-web',
include_relations = True
)
```
## Core Architecture
### Local-First Knowledge Storage
@@ -90,386 +232,7 @@ Basic Memory represents a fundamental breakthrough in knowledge management: it c
- Recent changes logs
- **Rich Metadata**: Frontmatter provides context without cluttering content
## The Semantic Layer
### memory:// URI Scheme
Think of this like "web addresses for your knowledge." Just as http:// links connect web pages, memory:// URIs connect pieces of knowledge:
```
memory://basic-memory/concepts/semantic-web # Direct concept reference
memory://*/technical-components # Cross-project view
memory://current/recent-changes # Timeline-based access
memory://project-x/decisions/* # Pattern-based queries
```
This creates a "semantic web" of your personal knowledge where:
- Every piece of information is directly addressable
- Patterns can match related concepts
- Knowledge can be traversed programmatically
- References work across projects and contexts
### Context Building
The system can automatically build rich context by:
1. Following semantic links to related concepts
2. Understanding relationship types and their meaning
3. Aggregating relevant information across projects
4. Maintaining historical context through versions
## AI Integration (MCP)
### Model Context Protocol
Basic Memory implements Anthropic's Model Context Protocol (MCP), enabling:
- AI tools that can navigate your knowledge graph
- Persistent context across conversations
- Structured data exchange with AI models
- Tool-based interaction with your knowledge base
### Smart Context Loading
When an AI needs context, the system can:
1. Parse memory:// URIs to locate relevant knowledge
2. Follow semantic links to related concepts
3. Build appropriate context summaries
4. Maintain conversation history with proper references
## Obsidian Integration
### Two-Way Compatibility
- **Files**: Standard markdown with frontmatter metadata
- **Links**: Wiki-links map to semantic relationships
- **Graphs**: Automatic visualization of knowledge connections
- **Search**: Full-text and semantic search capabilities
### Enhanced Navigation
- **Auto-Generated Indexes**: Dynamic directory of knowledge
- **Smart Lists**: Automatically updated views of related content
- **Timeline Views**: Track knowledge evolution
- **Status Boards**: Project and component tracking
### Preservation of Intent
- Human notes remain human-readable
- AI interactions maintain context
- Semantic connections preserve meaning
- All data stays in open formats
## The Technical Innovation
What makes Basic Memory special is how these components work together:
1. **Knowledge Capture**
- Write normally in Obsidian
- System maintains semantic structure
- Connections build automatically
- Context preserves naturally
2. **Knowledge Organization**
- Multiple simultaneous organizations
- Automatic index generation
- Semantic relationship tracking
- Timeline preservation
3. **Knowledge Access**
- Direct through memory:// URIs
- Visual through Obsidian graphs
- Semantic through AI tools
- Temporal through history tracking
4. **Knowledge Evolution**
- Natural growth through use
- Automatic relationship discovery
- Context building across sessions
- Pattern emergence over time
## Implementation Philosophy
The system follows key principles:
1. **Source of Truth**
- Markdown files are authoritative
- Database serves as queryable index
- All operations are atomic and safe
- Recovery is always possible
2. **Open Standards**
- Standard markdown format
- SQLite database
- URI-based addressing
- Git-compatible storage
3. **Local Control**
- All data stays local
- No cloud dependencies
- Standard backup options
- Easy data portability
4. **Extensibility**
- Clear API boundaries
- Standard protocols
- Pluggable components
- Open source core
## Future Capabilities
The architecture enables future features like:
1. **Enhanced Semantics**
- Relationship type inference
- Automatic categorization
- Pattern discovery
- Knowledge graph analytics
2. **Advanced AI Integration**
- Custom tool development
- Specialized context builders
- Pattern-based queries
- Semantic search enhancement
3. **Collaborative Features**
- Shared knowledge bases
- Team synchronization
- Access control
- Audit trails
4. **Extended Tooling**
- Custom visualizations
- Analysis tools
- Export formats
- Integration APIs
## Why This Matters
Basic Memory isn't just another note-taking app or knowledge base. It's a fundamental rethinking of how personal knowledge can be:
- Captured without friction
- Organized without overhead
- Accessed naturally
- Enhanced through AI interaction
- Preserved for the long term
By creating a semantic layer that works equally well for humans and machines, while keeping everything local and under user control, we're building infrastructure for a new kind of personal knowledge management.
This is what makes it truly powerful: it enhances how you already work while enabling entirely new capabilities through its semantic understanding layer.
# Basic Memory: Practical Examples
## Project Structure Example
```
basic-memory/
├── indexes/
│ ├── technical-components.md
│ ├── project-status.md
│ ├── weekly-updates.md
│ └── design-decisions.md
├── entities/
│ ├── technical/
│ │ ├── memory-service.md
│ │ ├── entity-service.md
│ │ └── relation-service.md
│ ├── concepts/
│ │ ├── semantic-web.md
│ │ └── memory-protocol.md
│ └── projects/
│ ├── basic-memory.md
│ └── obsidian-integration.md
├── decisions/
│ ├── 20241210-file-structure.md
│ └── 20241210-obsidian-format.md
└── conversations/
└── 20241210-semantic-web-breakthrough.md
```
## Example Entity Document
```markdown
---
type: technical_component
created: 2024-12-10T15:30:00Z
updated: 2024-12-10T16:45:00Z
status: implementing
tags: [core, service, memory]
---
# Memory Service
Core service handling knowledge persistence and retrieval.
## Description
Provides unified interface for storing and accessing knowledge across filesystem and database, maintaining consistency and enabling semantic queries.
## Observations
- Implements filesystem-as-source-of-truth pattern
- Handles atomic file operations
- Maintains SQLite index
- Coordinates with entity and relation services
## Relations
- [[Entity_Service]] depends_on
- [[Relation_Service]] coordinates_with
- [[File_IO_Module]] uses
- [[SQLite_Schema]] implements
## Implementation Notes
- Uses async/await throughout
- Careful error handling for filesystem operations
- Proper SQLite transaction management
- Full test coverage
## References
- memory://basic-memory/decisions/20241210-file-structure
- memory://basic-memory/concepts/semantic-web
```
## Example Index Document
```markdown
---
type: index
indexType: technical_components
generated: 2024-12-10T17:00:00Z
autoUpdate: true
---
# Technical Components
## Core Services
- [[Memory_Service]] - Knowledge persistence and retrieval
- [[Entity_Service]] - Entity lifecycle management
- [[Relation_Service]] - Relationship handling
## Supporting Modules
- [[File_IO_Module]] - Atomic file operations
- [[Database_Service]] - SQLite management
- [[Index_Generator]] - Navigation aid creation
## Recent Updates
- Added observation support to Memory Service (2024-12-10)
- Improved error handling in File IO Module (2024-12-09)
- New index generation patterns (2024-12-08)
## Implementation Status
- ✅ Core file operations
- ✅ Entity management
- 🚧 Relation handling
- 📋 Advanced search
## Related Concepts
- [[Semantic_Web]]
- [[Memory_Protocol]]
- [[File_Structure_Design]]
```
# Basic Memory: Practical Examples
## Project Structure Example
```
basic-memory/
├── indexes/
│ ├── technical-components.md
│ ├── project-status.md
│ ├── weekly-updates.md
│ └── design-decisions.md
├── entities/
│ ├── technical/
│ │ ├── memory-service.md
│ │ ├── entity-service.md
│ │ └── relation-service.md
│ ├── concepts/
│ │ ├── semantic-web.md
│ │ └── memory-protocol.md
│ └── projects/
│ ├── basic-memory.md
│ └── obsidian-integration.md
├── decisions/
│ ├── 20241210-file-structure.md
│ └── 20241210-obsidian-format.md
└── conversations/
└── 20241210-semantic-web-breakthrough.md
```
## Example Entity Document
```markdown
---
type: technical_component
created: 2024-12-10T15:30:00Z
updated: 2024-12-10T16:45:00Z
status: implementing
tags: [core, service, memory]
---
# Memory Service
Core service handling knowledge persistence and retrieval.
## Description
Provides unified interface for storing and accessing knowledge across filesystem and database, maintaining consistency and enabling semantic queries.
## Observations
- Implements filesystem-as-source-of-truth pattern
- Handles atomic file operations
- Maintains SQLite index
- Coordinates with entity and relation services
## Relations
- [[Entity_Service]] depends_on
- [[Relation_Service]] coordinates_with
- [[File_IO_Module]] uses
- [[SQLite_Schema]] implements
## Implementation Notes
- Uses async/await throughout
- Careful error handling for filesystem operations
- Proper SQLite transaction management
- Full test coverage
## References
- memory://basic-memory/decisions/20241210-file-structure
- memory://basic-memory/concepts/semantic-web
```
## Example Index Document
- The AI writes records information in plain text markdown.
- Files can also be edited by the user.
```markdown
---
type: index
indexType: technical_components
generated: 2024-12-10T17:00:00Z
autoUpdate: true
---
# Technical Components
## Core Services
- [[Memory_Service]] - Knowledge persistence and retrieval
- [[Entity_Service]] - Entity lifecycle management
- [[Relation_Service]] - Relationship handling
## Supporting Modules
- [[File_IO_Module]] - Atomic file operations
- [[Database_Service]] - SQLite management
- [[Index_Generator]] - Navigation aid creation
## Recent Updates
- Added observation support to Memory Service (2024-12-10)
- Improved error handling in File IO Module (2024-12-09)
- New index generation patterns (2024-12-08)
## Implementation Status
- ✅ Core file operations
- ✅ Entity management
- 🚧 Relation handling
- 📋 Advanced search
## Related Concepts
- [[Semantic_Web]]
- [[Memory_Protocol]]
- [[File_Structure_Design]]
```
## Semantic Web Visualization
- The AI can easily produce visualizations of related data in memory.
```mermaid
graph TD
@@ -528,83 +291,248 @@ graph TD
class SW,MP,URI knowledge
```
## Enhanced Navigation Examples
## Obsidian Integration: The Human Interface
This structure enables multiple ways to navigate and understand the knowledge base:
- Directory structure for traditional navigation
- Wiki-links for relationship exploration
- Status boards for project tracking
- Timeline views for historical context
- Component views for technical understanding
### Visual Knowledge Navigation
Obsidian provides:
- Interactive graph visualization
- Wiki-style navigation
- Familiar markdown editing
- Full-text search
Each view is auto-generated and updated, ensuring information stays current while maintaining the core principle of markdown files as the source of truth.
### Two-Way Sync
- Files editable in Obsidian or programmatically
- Database stays in sync with files
- Changes propagate automatically
- History preserved through git
1. **Timeline View** (`indexes/weekly-updates.md`):
```markdown
# Weekly Development Updates
### Knowledge Graph with Relations
## Week of 2024-12-10
### New Features
- [[Memory_Service]] Added observation support
- [[File_IO_Module]] Improved error handling
```mermaid
graph TD
%% Core components
MS[Memory Service]
ES[Entity Service]
RS[Relation Service]
FIO[File IO Module]
DB[(SQLite DB)]
SW{Semantic Web}
%% Show explicit relation types
MS --> |depends_on| ES
MS --> |coordinates_with| RS
MS --> |uses| FIO
ES --> |maintains_index_in| DB
RS --> |maintains_index_in| DB
FIO --> |writes_to| DB
%% Semantic relationships
SW --> |enables| MS
SW --> |implemented_by| RS
%% Implementation relations
ES --> |validates| FIO
RS --> |notifies| ES
%% Design influence
SW -.-> |inspires| RS
SW -.-> |guides| ES
### Key Decisions
- [[20241210-file-structure]] Finalized directory organization
- [[20241210-obsidian-format]] Standardized markdown format
%% Style for dark mode
classDef default fill:#2d2d2d,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
classDef concept fill:#353535,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
%% Apply styles
class SW concept
```
---
### In Progress
- [[Relation_Service]] Implementing core functionality
- [[Search_Module]] Designing advanced queries
# Part 3: Implementation Examples
## Project Structure
```
basic-memory/
├── indexes/ # Auto-generated navigation aids
│ ├── technical-components.md
│ ├── project-status.md
│ └── weekly-updates.md
├── entities/ # Core knowledge storage
│ ├── technical/
│ │ ├── memory-service.md
│ │ └── entity-service.md
│ ├── concepts/
│ │ └── semantic-web.md
│ └── projects/
│ └── basic-memory.md
├── decisions/ # Design history
│ └── 20241210-file-structure.md
└── conversations/ # AI interaction records
└── 20241210-semantic-web-breakthrough.md
```
2. **Component Status** (`indexes/technical-components.md`):
## Knowledge Representation
### Entity Document Example
```markdown
# Technical Components Status
---
type: technical_component
created: 2024-12-10T15:30:00Z
updated: 2024-12-10T16:45:00Z
status: implementing
tags: [core, service, memory]
---
## Active Development
🚧 [[Relation_Service]]
- Implementing core functionality
- Adding validation rules
- Writing tests
# Memory Service
## Recently Completed
✅ [[Memory_Service]]
- Added observation support
- Improved error handling
- Full test coverage
Core service handling knowledge persistence and retrieval.
## Up Next
📋 [[Search_Module]]
- Design query language
- Implement basic search
- Add advanced filters
## Description
Provides unified interface for storing and accessing knowledge.
## Observations
- Implements filesystem-as-source-of-truth pattern
- Handles atomic file operations
- Maintains SQLite index
## Relations
- [[Entity_Service]] depends_on
- [[File_IO_Module]] uses
## References
- memory://basic-memory/decisions/20241210-file-structure
```
3. **Project Overview** (`indexes/project-status.md`):
### Auto-Generated Index Example
```markdown
# Project Status Overview
---
type: index
indexType: technical_components
generated: 2024-12-10T17:00:00Z
autoUpdate: true
---
## Current Focus
- Implementing relation management
- Improving search capabilities
# Technical Components
## Core Services
- [[Memory_Service]] - Knowledge persistence
- [[Entity_Service]] - Entity lifecycle
- [[Relation_Service]] - Relationships
## Recent Updates
- Added observation support (2024-12-10)
- Improved error handling (2024-12-09)
## Implementation Status
- ✅ Core file operations
- 🚧 Relation handling
- 📋 Advanced search
```
### Visualize Temporal Knowledge
```mermaid
graph TD
%% Knowledge evolution
V1[Initial Design]
V2[Prototype]
V3[Current Version]
V4[Next Release]
%% Version relations
V1 -->|evolves_to| V2
V2 -->|improves_into| V3
V3 -->|planned_upgrade| V4
%% Historical insights
D1{Design Decision 1}
D2{Design Decision 2}
L1{Lesson Learned}
%% Historical relations
D1 -->|influences| V2
D2 -->|shapes| V3
L1 -->|informs| V4
V2 -->|validates| D1
V3 -->|proves| L1
classDef default fill:#2d2d2d,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
classDef insight fill:#404040,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
class D1,D2,L1 insight
```
# Current Status & Next Steps
```mermaid
graph LR
%% Timeline nodes
N[Now] --> IP[In Progress] --> NS[Next Steps]
%% Current features
subgraph "Working Now"
F1[File Operations]
F2[Entity Management]
F3[MCP Integration]
end
%% In progress
subgraph "In Progress"
P1[Relation Service]
P2[Search Features]
P3[Index Generation]
end
%% Next steps
subgraph "Coming Soon"
S1[Obsidian Layer]
S2[Enhanced Navigation]
S3[CLI Tools]
end
%% Connect timeline to features
N --> F1
N --> F2
N --> F3
IP --> P1
IP --> P2
IP --> P3
NS --> S1
NS --> S2
NS --> S3
classDef default fill:#2d2d2d,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
classDef timeline fill:#353535,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
class N,IP,NS timeline
```
## Implemented
- Core file operations and database sync
- Basic entity and relation management
- Markdown file format and parsing
- SQLite schema and indexing
- Initial MCP integration
## In Progress
- Relation service completion
- Enhanced search capabilities
- Index generation improvements
- Documentation updates
## Recent Progress
### Technical
- Core services stable
- File operations reliable
- Basic search working
## Coming Soon
- Obsidian compatibility layer
- Enhanced navigation features
- Improved AI context building
- CLI tool suite for managing AI sync
### Documentation
- Architecture guide updated
- API documentation current
- Example files created
## Next Steps
1. Complete relation service
2. Enhance search functionality
3. Add visualization tools
4. Improve error handling
```
## Get Involved
Basic Memory is open source (AGPL3) and ready for:
- Community Edition: Free, open source for technical users
- Personal Edition: Easy-to-use desktop app for everyone
- Team Edition: Secure collaboration for groups
Every edition maintains our core principle: your knowledge stays yours.
Built with ♥️ by Basic Machines. Join us in building tools for better thinking at basic-machines.co
tasks.md
+421 -33
View File
@@ -3,23 +3,25 @@
## Current Focus
### Observation Management
Implement update/remove functionality for observations with a focus on maintainability and consistency with our "filesystem is source of truth" principle.
Implement update/remove functionality for observations with a focus on maintainability and consistency with our "
filesystem is source of truth" principle.
Options under consideration:
1. Bulk Update Approach
- Update all observations at once
- Pros:
- Simpler file operations
- No need to match on observation content
- Easier database synchronization
- Very consistent with "filesystem is source of truth"
- Cons:
- Less efficient - rewrites everything for small changes
- Potential concurrency implications
- Update all observations at once
- Pros:
- Simpler file operations
- No need to match on observation content
- Easier database synchronization
- Very consistent with "filesystem is source of truth"
- Cons:
- Less efficient - rewrites everything for small changes
- Potential concurrency implications
2. Tracked Observations Approach
- Use markdown comments for observation IDs
- Use markdown comments for observation IDs
```markdown
# Entity Name
type: entity_type
@@ -28,41 +30,427 @@ Options under consideration:
- <!-- obs-id: abc123 -->
This is an observation
```
- Pros:
- Can track individual observations
- Enables precise updates/deletes
- Cons:
- More complex markdown parsing
- IDs visible in markdown
- Pros:
- Can track individual observations
- Enables precise updates/deletes
- Cons:
- More complex markdown parsing
- IDs visible in markdown
3. Diff-based Approach
- Implement observation-aware diffing
- Track changes at observation level
- Pros:
- More efficient updates
- Preserves manual edits
- Cons:
- More complex implementation
- Need to handle merge conflicts
- Implement observation-aware diffing
- Track changes at observation level
- Pros:
- More efficient updates
- Preserves manual edits
- Cons:
- More complex implementation
- Need to handle merge conflicts
4. Position-based Management
- Track observations by their position/order
- Pros:
- No need for explicit IDs
- Clean markdown
- Cons:
- Fragile if order changes
- Hard to handle concurrent edits
- Track observations by their position/order
- Pros:
- No need for explicit IDs
- Clean markdown
- Cons:
- Fragile if order changes
- Hard to handle concurrent edits
## Completed
- [x] Extract file operations to fileio.py module
- [x] Update EntityService to use fileio functions
- [x] Initial ObservationService implementation
- [x] Basic test coverage
## Future Work
- [ ] Implement observation updates/removals (exploring options above)
- [ ] Proper session management for concurrent operations
- [ ] EntityService tests using new fileio module
- [ ] More sophisticated search functionality
- [ ] Handle markdown formatting edge cases
- [ ] Handle markdown formatting edge cases
## TODO
### refactor input schema
1. Observations Format:
Old (JSON) way I tried first:
```python
"observations": ["First observation", "Second observation"] # Simple string array
```
New required format:
```python
"observations": [
{"content": "First observation"},
{"content": "Second observation"}
] # Array of objects with content field
```
2. Relations Format:
Old way:
```python
"relations": [
{"from": "EntityName", "to": "OtherEntity", "relationType": "relates_to"} # Using names
]
```
New format:
```python
"relations": [
{"fromId": "20241210-entity-id", "toId": "20241210-other-id", "relationType": "relates_to"} # Using IDs
]
```
My preferences:
1. For observations: The simple string array felt more intuitive for basic use, but I can see the benefits of the object
format:
- Allows for additional metadata (context, timestamps, etc.)
- More explicit about what each field means
- Consistent with how we'd want to store this in a database
2. For relations: Using IDs is technically better but requires an extra lookup step in my workflow:
- I have to first create the entities to get their IDs
- Then use those IDs to create relations
- Makes it harder to create entities and relations in a single step
Suggestions for making it more intuitive:
1. For observations: We could have a helper function that accepts either format:
```python
# Both would work:
create_entities([{
"name": "Entity",
"entityType": "type",
"observations": ["Simple string obs"] # Auto-converted to object format
}])
create_entities([{
"name": "Entity",
"entityType": "type",
"observations": [{"content": "Full object obs"}] # Native format
}])
```
2. For relations: Maybe allow a name-based helper function:
```python
# Instead of requiring IDs:
create_relations_by_name([{
"from": "EntityName",
"to": "OtherEntity",
"relationType": "relates_to"
}])
```
3. A combined creation function for when we want to create entities and their relations together:
```python
create_entity_with_relations({
"entity": {
"name": "NewEntity",
"entityType": "type",
"observations": ["Obs 1", "Obs 2"]
},
"relations": [{
"to": "ExistingEntity",
"relationType": "relates_to"
}]
})
```
The current schema is more "correct" from a software engineering perspective, but these helpers could make it more
natural to use while maintaining the rigorous underlying structure. What do you think about these suggestions? Would you
prefer to keep it strict for clarity, or add some convenience layers?
### entity file organization
- my problems
- wall of text is hard to scan visually
- files are not ordered or grouped granular enough. Only `<date>_<entity_name>.md`
- hard to tell when a new entity file is added
Possible fixes:
- use subdirectories?
## TASKS
1. **Core Functionality Improvements**
- [ ] entity.description addition
- [ ] subdirectories
- Paul needs this for markdown view
- [ ] improve tool api
- [ ] Choose and implement observation update/removal strategy
- [ ] Handle relationship updates in files
- [ ] Complete full CRUD operations
- delete
- [ ] Improve search functionality (currently broken as we discovered)
### Suggested Sequence
1. **Schema Update First**
- Add `entity.description` field
- This affects database, Pydantic models, and file format
- Good foundation for other changes
2. **File Organization**
- Add subdirectory support
- Affects:
- File path handling
- Entity loading/saving
- URI resolution
- Will make Paul's markdown viewing experience better
3. **Tool API Improvements**
- Cleaner input/output schemas
- More consistent patterns
- Better error handling
- This sets us up for implementing the remaining operations
4. **Core Operations**
- Implement delete operations
- Update/remove observations
- Relationship updates in files
- Building on the improved API
5. **Search Fix**
- Can properly tackle this after file organization
- Will benefit from improved schema
Would you like me to:
1. Start with the schema update for entity.description?
2. Plan out the subdirectory implementation?
3. Or focus on a different area?
I think the schema update would be a clean, contained change to start with, but I'm happy to tackle whichever part you think would be most valuable first.
2. **Robustness & Testing**
- Fix DI issues
- Learn from fastmcp patterns
- Markdown service
- markdown.py
-python-frontmatter
- Complete test coverage
- Expand testing across services
- 100% coverate
- Improve error handling and logging
- Add comprehensive type hints
3. **Architecture Improvements**
- Handle concurrent file operations safely
- Implement proper session management
- Balance file operations and DB sync
- Handle markdown formatting edge cases
4. **Documentation & Infrastructure**
- Document core modules
- Implement proper backup strategy
- Add file change versioning
- Improve CLI interface
## Ideas
- need update tool
### 2-way sync
- Enable updates to the markdown files to be able to be seen by AI
- possible via tool sync
- filesystem notifications via agent?
- Claude can use `file_write` tool to edit Entity files also
### Projects
- support multiple projects
- figure out flow
- load project at startup?
- switch project during chat?
### References
- better support for ref:// references
- should we call them memory://<project>/<entity>
- use Prompt to invoke reference uri
### Entity File format
- Consider using wiki link format:
[[20241210-ai_human_collaboration_model]] improves
instead of
[20241210-basic-memory] validates_design_of
- use frontmatter for file header
### Code
- cleanup server.py
- use markdown.py?
- fastmcp?
- Entity.description
### Other Features
- Search
- webui
- python notebook?
- vector eb extension for sqlite
#### Obsidian
- use as file viewer editor
- create knowledge graph?
#### Save chats
I'll sketch out a potential schema for chat sessions in our system:
```
{
`entities`: [
{
`name`: `Chat_Entity_Design`,
`entityType`: `design_proposal`,
`observations`: [
{
`content`: `Entity Schema:
type: chat_session
date: ISO timestamp
participants: [human, ai]
topic: string
context_refs: [memory://<project>/<entity_id>]
key_decisions: [string]
summary: string`
},
{
`content`: `File Format (frontmatter):
---
type: chat_session
date: 2024-12-10T10:30:00Z
participants:
- human: paul
- ai: claude
topic: Chat Session Storage Design
context_refs:
- memory://basic-memory/20241210-chat-entity-design
key_decisions:
- Store chats as first-class entities
- Use memory:// URI scheme
summary: Designed schema for chat storage
---`
},
{
`content`: `Example Relations:
- chat_session references design_proposal
- chat_session implements feature
- chat_session discusses concept
- chat_session continues_from previous_chat`
},
{
`content`: `Auto-generation approach:
1. At end of chat, Claude summarizes key points
2. Creates chat entity with metadata
3. Adds relations to referenced entities
4. Updates any entities modified during chat`
},
{
`content`: `Integration points:
- memory:// URI scheme for references
- Relations to track context chain
- File format matches entity schema
- Automatic metadata generation`
}
]
}
]
}
```
```
{
`entities`: [
{
`name`: `Chat_Session_Workflow`,
`entityType`: `process`,
`observations`: [
{
`content`: `Start of chat:
- Load any referenced context via memory:// URIs
- Initialize new chat session metadata
- Track entities being discussed/modified`
},
{
`content`: `During chat:
- Update references as new entities are mentioned
- Track key decisions and changes
- Note any new relations discovered`
},
{
`content`: `End of chat:
- Generate summary and key points
- Create chat session entity
- Add relations to referenced entities
- Update any modified entities`
},
{
`content`: `Future chat reference:
- Can reference previous chat via memory:// URI
- Loads relevant context and decisions
- Creates continues_from relation automatically`
}
]
}
]
}
```
Key aspects of this design:
1. Chat Session as Entity
- Clear metadata (participants, date, topic)
- Explicit references to other entities via memory:// URIs
- Captures key decisions and summary
- Uses frontmatter for clean file format
2. Rich Relations
- Can track chat-to-chat continuity
- Links to entities discussed/modified
- Captures purpose (discusses, implements, etc.)
- Maintains context chain
3. Automated Workflow
- I could generate metadata during chat
- Create summary and relations at end
- Update any modified entities
- Makes context loading explicit
4. Integration
- memory:// URI scheme fits naturally
- File format matches our entity pattern
- Two-way links between chats and entities
- Clear context persistence model
The nice thing about this design is that it makes chat sessions "first-class citizens" in our knowledge graph while
keeping everything in human-readable markdown files.
Would you like me to:
1. Sketch out what this chat would look like as an entity?
2. Detail the MCP tool changes needed?
3. Mock up the file format more precisely?
4. Something else?