mirror of
https://github.com/basicmachines-co/basic-memory
synced 2026-06-21 13:47:35 +00:00
remove unused files
This commit is contained in:
phernandez
@@ -1,11 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<module type="PYTHON_MODULE" version="4">
|
||||
<component name="NewModuleRootManager" inherit-compiler-output="true">
|
||||
<exclude-output />
|
||||
<content url="file://$MODULE_DIR$">
|
||||
<excludeFolder url="file://$MODULE_DIR$/.venv" />
|
||||
</content>
|
||||
<orderEntry type="jdk" jdkName="Python 3.9 (basic-memory)" jdkType="Python SDK" />
|
||||
<orderEntry type="sourceFolder" forTests="false" />
|
||||
</component>
|
||||
</module>
|
||||
@@ -1,35 +0,0 @@
|
||||
CREATE TABLE IF NOT EXISTS "schema_migrations" (version varchar(128) primary key);
|
||||
CREATE TABLE IF NOT EXISTS "observation" (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
entity_id TEXT NOT NULL,
|
||||
content TEXT NOT NULL, -- the actual observation text
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
context TEXT, -- where this observation came from
|
||||
FOREIGN KEY (entity_id) REFERENCES "entity"(id)
|
||||
);
|
||||
CREATE TABLE IF NOT EXISTS "relation" (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
from_entity_id TEXT NOT NULL,
|
||||
to_entity_id TEXT NOT NULL,
|
||||
relation_type TEXT NOT NULL, -- the verb describing the relationship
|
||||
context TEXT, -- optional context about the relationship
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
FOREIGN KEY (from_entity_id) REFERENCES "entity"(id),
|
||||
FOREIGN KEY (to_entity_id) REFERENCES "entity"(id),
|
||||
-- Ensure we don't duplicate the exact same relationship
|
||||
UNIQUE(from_entity_id, to_entity_id, relation_type)
|
||||
);
|
||||
CREATE TABLE IF NOT EXISTS "entity" (
|
||||
id TEXT PRIMARY KEY,
|
||||
name TEXT NOT NULL,
|
||||
type TEXT NOT NULL,
|
||||
description TEXT NULL,
|
||||
"references" TEXT NOT NULL DEFAULT '',
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
-- Dbmate schema migrations
|
||||
INSERT INTO "schema_migrations" (version) VALUES
|
||||
('20240101000000'),
|
||||
('20240102000000'),
|
||||
('20241210213454');
|
||||
@@ -1,38 +0,0 @@
|
||||
-- migrate:up
|
||||
-- Make description column explicitly nullable by recreating table
|
||||
CREATE TABLE entity_new (
|
||||
id TEXT PRIMARY KEY,
|
||||
name TEXT NOT NULL,
|
||||
entity_type TEXT NOT NULL,
|
||||
description TEXT NULL,
|
||||
"references" TEXT NOT NULL DEFAULT '',
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
-- Copy existing data
|
||||
INSERT INTO entity_new (id, name, entity_type, description, "references", created_at)
|
||||
SELECT id, name, entity_type, description, "references", created_at FROM entity;
|
||||
|
||||
-- Drop old table and rename new one
|
||||
DROP TABLE entity;
|
||||
ALTER TABLE entity_new RENAME TO entity;
|
||||
|
||||
-- migrate:down
|
||||
-- Restore NOT NULL constraint by recreating table
|
||||
CREATE TABLE entity_new (
|
||||
id TEXT PRIMARY KEY,
|
||||
name TEXT NOT NULL,
|
||||
entity_type TEXT NOT NULL,
|
||||
description TEXT NOT NULL,
|
||||
"references" TEXT NOT NULL DEFAULT '',
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
);
|
||||
|
||||
-- Copy data (will fail if any nulls exist)
|
||||
INSERT INTO entity_new (id, name, entity_type, description, "references", created_at)
|
||||
SELECT id, name, entity_type, description, "references", created_at FROM entity;
|
||||
|
||||
-- Drop old table and rename new one
|
||||
DROP TABLE entity;
|
||||
ALTER TABLE entity_new RENAME TO entity;
|
||||
@@ -1,38 +0,0 @@
|
||||
-- migrate:up
|
||||
-- Make description column explicitly nullable by recreating table
|
||||
CREATE TABLE entity_new (
|
||||
id TEXT PRIMARY KEY,
|
||||
name TEXT NOT NULL,
|
||||
entity_type TEXT NOT NULL,
|
||||
description TEXT NULL,
|
||||
"references" TEXT NULL,
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
-- Copy existing data
|
||||
INSERT INTO entity_new (id, name, entity_type, description, "references", created_at)
|
||||
SELECT id, name, entity_type, description, "references", created_at FROM entity;
|
||||
|
||||
-- Drop old table and rename new one
|
||||
DROP TABLE entity;
|
||||
ALTER TABLE entity_new RENAME TO entity;
|
||||
|
||||
-- migrate:down
|
||||
-- Restore NOT NULL constraint by recreating table
|
||||
CREATE TABLE entity_new (
|
||||
id TEXT PRIMARY KEY,
|
||||
name TEXT NOT NULL,
|
||||
entity_type TEXT NOT NULL,
|
||||
description TEXT NULL,
|
||||
"references" TEXT NOT NULL DEFAULT '',
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
);
|
||||
|
||||
-- Copy data (will fail if any nulls exist)
|
||||
INSERT INTO entity_new (id, name, entity_type, description, "references", created_at)
|
||||
SELECT id, name, entity_type, description, "references", created_at FROM entity;
|
||||
|
||||
-- Drop old table and rename new one
|
||||
DROP TABLE entity;
|
||||
ALTER TABLE entity_new RENAME TO entity;
|
||||
@@ -1,5 +0,0 @@
|
||||
-- migrate:up
|
||||
ALTER TABLE entity DROP COLUMN "references";
|
||||
|
||||
-- migrate:down
|
||||
ALTER TABLE entity ADD COLUMN "references" TEXT DEFAULT NULL;
|
||||
@@ -1,8 +0,0 @@
|
||||
-- migrate:up
|
||||
-- Add unique index on entity type and name combination
|
||||
CREATE UNIQUE INDEX idx_entity_type_name ON entity(entity_type, name);
|
||||
|
||||
-- migrate:down
|
||||
|
||||
-- Restore original schema
|
||||
DROP INDEX IF EXISTS idx_entity_type_name;
|
||||
@@ -1,50 +0,0 @@
|
||||
-- migrate:up
|
||||
|
||||
-- Create new observation table with correct default
|
||||
CREATE TABLE observation_new (
|
||||
id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
|
||||
entity_id VARCHAR NOT NULL,
|
||||
content VARCHAR NOT NULL,
|
||||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
context VARCHAR,
|
||||
FOREIGN KEY(entity_id) REFERENCES entity (id) ON DELETE CASCADE
|
||||
);
|
||||
|
||||
-- Copy data from old observation table
|
||||
INSERT INTO observation_new
|
||||
SELECT id, entity_id, content, COALESCE(created_at, CURRENT_TIMESTAMP), context
|
||||
FROM observation;
|
||||
|
||||
-- Drop old observation table and rename new one
|
||||
DROP TABLE observation;
|
||||
ALTER TABLE observation_new RENAME TO observation;
|
||||
|
||||
-- Recreate observation index
|
||||
CREATE INDEX ix_observation_entity_id ON observation (entity_id);
|
||||
|
||||
-- Create new relation table with correct default
|
||||
CREATE TABLE relation_new (
|
||||
id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
|
||||
from_id VARCHAR NOT NULL,
|
||||
to_id VARCHAR NOT NULL,
|
||||
relation_type VARCHAR NOT NULL,
|
||||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
context VARCHAR,
|
||||
FOREIGN KEY(from_id) REFERENCES entity (id) ON DELETE CASCADE,
|
||||
FOREIGN KEY(to_id) REFERENCES entity (id) ON DELETE CASCADE
|
||||
);
|
||||
|
||||
-- Copy data from old relation table
|
||||
INSERT INTO relation_new
|
||||
SELECT id, from_id, to_id, relation_type, COALESCE(created_at, CURRENT_TIMESTAMP), context
|
||||
FROM relation;
|
||||
|
||||
-- Drop old relation table and rename new one
|
||||
DROP TABLE relation;
|
||||
ALTER TABLE relation_new RENAME TO relation;
|
||||
|
||||
-- Recreate relation indexes
|
||||
CREATE INDEX ix_relation_from_id ON relation (from_id);
|
||||
CREATE INDEX ix_relation_to_id ON relation (to_id);
|
||||
|
||||
-- migrate:down
|
||||
@@ -1 +0,0 @@
|
||||
gi
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
id: 20240101-basic-memory
|
||||
type: Project
|
||||
created: 2024-01-01T12:00:00Z
|
||||
context: basic-memory-design-discussion
|
||||
---
|
||||
|
||||
# Basic Memory
|
||||
|
||||
Local-first knowledge management system that combines Zettelkasten methodology with knowledge graphs. Built using SQLite and markdown files, it enables seamless capture and connection of ideas while maintaining user control over data.
|
||||
|
||||
## Observations
|
||||
- Combines Zettelkasten with knowledge graph and MCP
|
||||
- Built on SQLite for local-first storage
|
||||
- Uses entities and relations matching LLM thinking patterns
|
||||
- Everything readable/writable as markdown
|
||||
- Project isolation for focused context
|
||||
- Core components: knowledge graph, MCP tools, notebook interface
|
||||
- Follows Basic Machines DIY philosophy
|
||||
|
||||
## Relations
|
||||
- [20240101-basic-machines] developed_by | Created as part of Basic Machines open source portfolio
|
||||
- [20240101-basic-foundation] built_on | Uses Basic Foundation for core infrastructure
|
||||
- [20240101-diy-ethics] follows | Implements DIY principles through local-first design
|
||||
- [20240101-ai-human-development-methodology] implements | Uses knowledge graphs for AI-human collaboration
|
||||
|
||||
## References
|
||||
- Zettelkasten.de introduction
|
||||
- MCP Memory Server documentation
|
||||
@@ -1,340 +0,0 @@
|
||||
## 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.
|
||||
|
||||
|
||||
## Practical info
|
||||
|
||||
@@ -1,450 +0,0 @@
|
||||
# Basic Memory Obsidian Integration Design
|
||||
|
||||
## Why Basic Memory + Obsidian Integration is a Game-Changer
|
||||
|
||||
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
|
||||
|
||||
### 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
|
||||
|
||||
### Perfect For
|
||||
- Researchers using AI for discovery
|
||||
- Developers managing complex projects
|
||||
- Writers organizing ideas and drafts
|
||||
- Knowledge workers synthesizing information
|
||||
- Anyone who wants to think better with AI
|
||||
|
||||
### The Magic
|
||||
Basic Memory provides the structure and AI integration. Obsidian provides the visualization and navigation. Together, they create a system that's greater than the sum of its parts - a truly augmented intelligence platform that grows with you.
|
||||
|
||||
Best part? It builds on tools you might already use, extending them naturally rather than replacing them. This isn't just another AI tool - it's a way to make your existing knowledge management system AI-native.
|
||||
|
||||
## Overview
|
||||
|
||||
Basic Memory will adopt Obsidian-compatible markdown formatting to enable seamless integration with Obsidian's powerful knowledge management features. This leverages Obsidian's existing user base and visualization capabilities while maintaining Basic Memory's rigorous knowledge graph structure.
|
||||
|
||||
## File Format
|
||||
|
||||
### Entity Files
|
||||
```markdown
|
||||
---
|
||||
type: <entity_type>
|
||||
created: <ISO timestamp>
|
||||
updated: <ISO timestamp>
|
||||
description: Short description of entity purpose
|
||||
tags: [<entity_type>, <category>, ...]
|
||||
---
|
||||
|
||||
# Entity Name
|
||||
|
||||
## Description
|
||||
Detailed entity description
|
||||
|
||||
## Observations
|
||||
- First observation
|
||||
- Second observation
|
||||
- etc...
|
||||
|
||||
## Relations
|
||||
- [[RelatedEntity]] implements
|
||||
- [[AnotherEntity]] depends_on
|
||||
- [[ThirdEntity]] relates_to
|
||||
|
||||
## References
|
||||
- Source links, citations, etc.
|
||||
```
|
||||
|
||||
### Index Files
|
||||
|
||||
#### Entity Type Index
|
||||
```markdown
|
||||
---
|
||||
type: index
|
||||
index_type: entity_type
|
||||
entity_type: technical_component
|
||||
auto_generated: true
|
||||
updated: <ISO timestamp>
|
||||
---
|
||||
|
||||
# Technical Components
|
||||
|
||||
## Active Components
|
||||
- [[Component1]] - Short description
|
||||
- [[Component2]] - Short description
|
||||
|
||||
## In Development
|
||||
- [[PlannedComponent]] - Development status
|
||||
|
||||
## Recently Updated
|
||||
- [[UpdatedComponent]] - Change summary
|
||||
```
|
||||
|
||||
#### Timeline Index
|
||||
```markdown
|
||||
---
|
||||
type: index
|
||||
index_type: timeline
|
||||
period: weekly
|
||||
auto_generated: true
|
||||
updated: <ISO timestamp>
|
||||
---
|
||||
|
||||
# Weekly Development Log
|
||||
|
||||
## Week of 2024-12-10
|
||||
### New Components
|
||||
- [[NewComponent]] - Added component for X
|
||||
### Updates
|
||||
- [[ExistingComponent]] - Improved functionality Y
|
||||
### Decisions
|
||||
- [[DecisionRecord]] - Chose approach Z
|
||||
```
|
||||
|
||||
#### Project Status Index
|
||||
```markdown
|
||||
---
|
||||
type: index
|
||||
index_type: status
|
||||
auto_generated: true
|
||||
updated: <ISO timestamp>
|
||||
---
|
||||
|
||||
# Project Status
|
||||
|
||||
## Active Development
|
||||
- [[CurrentFeature]] - Implementation status
|
||||
- [[PlannedFeature]] - Next in queue
|
||||
|
||||
## Recent Decisions
|
||||
- [[Decision1]] - Impact and context
|
||||
- [[Decision2]] - Rationale
|
||||
|
||||
## Known Issues
|
||||
- [[Issue1]] - Status and plan
|
||||
```
|
||||
|
||||
## Implementation Approach
|
||||
|
||||
### 1. File Generation
|
||||
- Update MemoryService to write Obsidian-compatible markdown
|
||||
- Add frontmatter support to file operations
|
||||
- Implement wiki-link format for relations
|
||||
- Support Obsidian tags in frontmatter
|
||||
|
||||
### 2. Index Generation Service
|
||||
```python
|
||||
class IndexGenerationService:
|
||||
def __init__(self, memory_service, file_service):
|
||||
self.memory_service = memory_service
|
||||
self.file_service = file_service
|
||||
self.index_configs = self.load_index_configs()
|
||||
|
||||
async def update_indexes(self, trigger_entity=None):
|
||||
"""Update affected indexes when entities change"""
|
||||
for config in self.index_configs:
|
||||
if self.should_update_index(config, trigger_entity):
|
||||
await self.generate_index(config)
|
||||
|
||||
async def generate_index(self, config):
|
||||
"""Generate specific index based on config"""
|
||||
entities = await self.query_relevant_entities(config)
|
||||
content = self.format_index_content(config, entities)
|
||||
await self.file_service.write_index(config.name, content)
|
||||
```
|
||||
|
||||
### 3. Update Triggers
|
||||
- Entity creation/modification
|
||||
- Scheduled updates (daily/weekly)
|
||||
- Manual refresh command
|
||||
- Bulk updates after imports
|
||||
|
||||
### 4. Integration Points
|
||||
- File system monitoring for external edits
|
||||
- Obsidian URI scheme support
|
||||
- Plugin hooks for future extensions
|
||||
- Graph data export
|
||||
|
||||
## User Experience
|
||||
|
||||
### Setup
|
||||
1. User points Obsidian vault to Basic Memory entity directory
|
||||
2. Basic Memory detects Obsidian usage, enables compatible features
|
||||
3. Index files are generated automatically
|
||||
4. Graph view becomes available immediately
|
||||
|
||||
### Regular Usage
|
||||
1. View knowledge graph in Obsidian
|
||||
2. Navigate via auto-generated indexes
|
||||
3. Edit files directly in Obsidian
|
||||
4. Basic Memory maintains consistency
|
||||
5. AI interactions continue updating graph
|
||||
|
||||
### Benefits
|
||||
1. Leverage existing Obsidian skills
|
||||
2. Multiple views of knowledge
|
||||
3. Rich visualization
|
||||
4. Local-first architecture
|
||||
5. Large ecosystem of plugins
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Implementation Priorities
|
||||
- Update file format
|
||||
- Create index generation service
|
||||
- Add Obsidian format detection
|
||||
- Implement update triggers
|
||||
|
||||
2. Future Enhancements
|
||||
- Custom index templates
|
||||
- Plugin development
|
||||
- Enhanced graph visualizations
|
||||
- Collaborative features
|
||||
|
||||
## Market Opportunity
|
||||
|
||||
1. Target Audience
|
||||
- Existing Obsidian users
|
||||
- AI power users
|
||||
- Knowledge workers
|
||||
- Researchers and writers
|
||||
|
||||
2. Value Proposition
|
||||
- Enhanced AI interaction
|
||||
- Automated organization
|
||||
- Structured knowledge capture
|
||||
- Familiar interface
|
||||
|
||||
3. Distribution
|
||||
- Direct to Obsidian community
|
||||
- AI tooling channels
|
||||
- Knowledge management space
|
||||
|
||||
|
||||
# Basic Memory Obsidian Integration Implementation Plan
|
||||
|
||||
## Phase 1: File Format Updates
|
||||
|
||||
### New File Format
|
||||
```markdown
|
||||
---
|
||||
type: technical_component
|
||||
created: 2024-12-10T15:30:00Z
|
||||
updated: 2024-12-10T15:30:00Z
|
||||
description: Core service handling entity lifecycle and persistence
|
||||
tags: [technical, implementation, core]
|
||||
---
|
||||
|
||||
# EntityService
|
||||
|
||||
## Description
|
||||
Manages entity lifecycle including creation, updates, and deletion while maintaining consistency between filesystem and database.
|
||||
|
||||
## Observations
|
||||
- Implements filesystem-as-source-of-truth pattern
|
||||
- Handles atomic file operations
|
||||
- Maintains SQLite index
|
||||
- Coordinates with other services
|
||||
|
||||
## Relations
|
||||
- [[FileIOService]] uses
|
||||
- [[ObservationService]] coordinates_with
|
||||
- [[DatabaseService]] maintains_index_in
|
||||
|
||||
## References
|
||||
- Link to relevant specs/docs
|
||||
```
|
||||
|
||||
### Implementation Tasks
|
||||
1. Update MemoryService
|
||||
```python
|
||||
class MemoryService:
|
||||
async def write_entity_file(self, entity):
|
||||
"""Generate Obsidian-compatible markdown"""
|
||||
frontmatter = {
|
||||
"type": entity.entity_type,
|
||||
"created": entity.created_at,
|
||||
"updated": entity.updated_at,
|
||||
"description": entity.description,
|
||||
"tags": [entity.entity_type, *self.generate_tags(entity)]
|
||||
}
|
||||
|
||||
content = f"""# {entity.name}
|
||||
|
||||
## Description
|
||||
{entity.description}
|
||||
|
||||
## Observations
|
||||
{self.format_observations(entity.observations)}
|
||||
|
||||
## Relations
|
||||
{self.format_relations_as_wikilinks(entity.relations)}
|
||||
"""
|
||||
return self.write_with_frontmatter(frontmatter, content)
|
||||
```
|
||||
|
||||
2. Add Frontmatter Support
|
||||
```python
|
||||
def write_with_frontmatter(self, frontmatter: dict, content: str) -> str:
|
||||
"""Combine frontmatter and content in Obsidian format"""
|
||||
yaml_fm = yaml.dump(frontmatter, sort_keys=False)
|
||||
return f"---\n{yaml_fm}---\n\n{content}"
|
||||
```
|
||||
|
||||
3. Wiki-Link Generation
|
||||
```python
|
||||
def format_relations_as_wikilinks(self, relations: List[Relation]) -> str:
|
||||
"""Convert relations to Obsidian wiki-link format"""
|
||||
return "\n".join(
|
||||
f"- [[{relation.to_entity.name}]] {relation.relation_type}"
|
||||
for relation in relations
|
||||
)
|
||||
```
|
||||
|
||||
## Phase 2: Index Generation
|
||||
|
||||
### Index Types and Configurations
|
||||
```python
|
||||
INDEX_CONFIGS = {
|
||||
"entity_type_index": {
|
||||
"template": "entity_type_index.md",
|
||||
"group_by": "entity_type",
|
||||
"sort_by": "updated_at",
|
||||
"update_trigger": "entity_change"
|
||||
},
|
||||
"timeline_index": {
|
||||
"template": "timeline_index.md",
|
||||
"group_by": "week",
|
||||
"sort_by": "created_at",
|
||||
"update_trigger": "daily"
|
||||
},
|
||||
"status_index": {
|
||||
"template": "status_index.md",
|
||||
"group_by": "status",
|
||||
"sort_by": "priority",
|
||||
"update_trigger": "entity_change"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### IndexGenerationService Implementation
|
||||
```python
|
||||
class IndexGenerationService:
|
||||
def __init__(self, memory_service: MemoryService):
|
||||
self.memory_service = memory_service
|
||||
self.index_configs = INDEX_CONFIGS
|
||||
|
||||
async def update_indexes(self, trigger: str = None):
|
||||
"""Update all indexes or those matching trigger"""
|
||||
for name, config in self.index_configs.items():
|
||||
if not trigger or config["update_trigger"] == trigger:
|
||||
await self.generate_index(name, config)
|
||||
|
||||
async def generate_index(self, name: str, config: dict):
|
||||
"""Generate single index based on configuration"""
|
||||
entities = await self.get_entities_for_index(config)
|
||||
grouped = self.group_entities(entities, config["group_by"])
|
||||
content = self.apply_template(config["template"], grouped)
|
||||
await self.memory_service.write_index_file(name, content)
|
||||
```
|
||||
|
||||
## Phase 3: Testing Strategy
|
||||
|
||||
### Test Cases
|
||||
1. File Format Tests
|
||||
```python
|
||||
async def test_entity_file_generation():
|
||||
"""Test Obsidian-compatible file generation"""
|
||||
entity = create_test_entity()
|
||||
content = await memory_service.write_entity_file(entity)
|
||||
|
||||
assert "---" in content # Has frontmatter
|
||||
assert "[[" in content # Has wiki-links
|
||||
assert content.count("##") >= 3 # Has sections
|
||||
```
|
||||
|
||||
2. Index Generation Tests
|
||||
```python
|
||||
async def test_index_generation():
|
||||
"""Test index file creation and updates"""
|
||||
await index_service.generate_index("entity_type_index")
|
||||
|
||||
content = await read_index_file("entity_type_index")
|
||||
assert "# Technical Components" in content
|
||||
assert "[[" in content # Has entity links
|
||||
```
|
||||
|
||||
3. Integration Tests
|
||||
```python
|
||||
async def test_obsidian_compatibility():
|
||||
"""Test full Obsidian compatibility"""
|
||||
# Create test vault
|
||||
# Generate entities and indexes
|
||||
# Verify Obsidian can parse and display
|
||||
```
|
||||
|
||||
## Phase 4: Launch Preparation
|
||||
|
||||
### Documentation Template
|
||||
```markdown
|
||||
# Basic Memory Obsidian Integration
|
||||
|
||||
## Setup
|
||||
1. Install Basic Memory
|
||||
2. Create/Open Obsidian vault
|
||||
3. Point to Basic Memory entity directory
|
||||
4. Configure index generation
|
||||
|
||||
## Features
|
||||
- Automatic knowledge graph visualization
|
||||
- Generated index views
|
||||
- Wiki-link navigation
|
||||
- AI integration via Basic Memory
|
||||
|
||||
## Usage Examples
|
||||
1. Creating new entities
|
||||
2. Navigating via indexes
|
||||
3. Using graph view
|
||||
4. AI interaction workflow
|
||||
```
|
||||
|
||||
### Launch Checklist
|
||||
- [ ] All tests passing
|
||||
- [ ] Example vault created
|
||||
- [ ] Setup documentation complete
|
||||
- [ ] Demo video recorded
|
||||
- [ ] Launch announcement drafted
|
||||
- [ ] Initial indexes refined
|
||||
- [ ] User feedback incorporated
|
||||
|
||||
## Implementation Schedule
|
||||
|
||||
1. Week 1: File Format
|
||||
- Implement new format
|
||||
- Add frontmatter support
|
||||
- Test basic Obsidian compatibility
|
||||
|
||||
2. Week 2: Index Generation
|
||||
- Build IndexGenerationService
|
||||
- Create initial templates
|
||||
- Test update triggers
|
||||
|
||||
3. Week 3: Testing & Refinement
|
||||
- Comprehensive testing
|
||||
- User testing with example vault
|
||||
- Refinement based on feedback
|
||||
|
||||
4. Week 4: Launch Prep
|
||||
- Documentation
|
||||
- Examples
|
||||
- Demo materials
|
||||
- Launch announcement
|
||||
@@ -1,538 +0,0 @@
|
||||
# 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.
|
||||
|
||||
## The Problem We're Solving
|
||||
|
||||
Current knowledge management tools force you to choose: hierarchical folders OR flat files, tags OR categories, local OR cloud storage. But real knowledge doesn't work that way. Ideas connect across multiple dimensions, linking and building in organic ways.
|
||||
|
||||
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:
|
||||
- **Spatial**: Navigate through folder hierarchies when that makes sense
|
||||
- **Semantic**: Follow relationship graphs between concepts
|
||||
- **Temporal**: Track how ideas evolve over time
|
||||
- **Contextual**: Jump directly to related knowledge through semantic links
|
||||
|
||||
Built on our core principles:
|
||||
- **Local First**: Your knowledge stays in SQLite databases you control
|
||||
- **Open Format**: Everything stored as human-readable markdown
|
||||
- **DIY Philosophy**: Simple tools that respect user agency
|
||||
- **True Open Source**: AGPL3 licensed - share, modify, improve
|
||||
|
||||
## Key Features
|
||||
|
||||
1. **Multidimensional Organization**
|
||||
- Use folders AND graphs AND timelines
|
||||
- Every piece of knowledge accessible from multiple angles
|
||||
- Natural organization that grows with use
|
||||
|
||||
2. **Rich Context**
|
||||
- Semantic linking between related concepts
|
||||
- Automatic indexes and navigation aids
|
||||
- Full history and evolution tracking
|
||||
|
||||
3. **AI-Ready Architecture**
|
||||
- Persistent context across conversations
|
||||
- Natural knowledge building through use
|
||||
- Semantic addressing for precise recall
|
||||
|
||||
4. **Obsidian Integration**
|
||||
- Beautiful visualization of knowledge graphs
|
||||
- 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.
|
||||
|
||||
Perfect for:
|
||||
- Researchers tracking complex projects
|
||||
- Developers managing technical knowledge
|
||||
- Writers organizing ideas and sources
|
||||
- Anyone collaborating deeply with AI
|
||||
|
||||
## Getting Started
|
||||
|
||||
Basic Memory is open source (AGPL3) and ready for:
|
||||
- Individual use (free forever)
|
||||
- Team adoption (commercial licensing available)
|
||||
- Custom integration (contact us)
|
||||
|
||||
# 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
|
||||
- **SQLite Database**: Fast, reliable, and portable storage
|
||||
- **Markdown Files**: Human-readable text files as source of truth
|
||||
- **Two-Way Sync**: Changes in either files or database propagate automatically
|
||||
- **Project Isolation**: Separate databases keep contexts clean and portable
|
||||
|
||||
### Intelligent File Organization
|
||||
- **Smart Folder Structure**: Organize by project, type, or timeline
|
||||
- **Auto-Generated Indexes**: Dynamic views of your knowledge
|
||||
- Technical component listings
|
||||
- Project status dashboards
|
||||
- Timeline views
|
||||
- Recent changes logs
|
||||
- **Rich Metadata**: Frontmatter provides context without cluttering content
|
||||
|
||||
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
%% Define nodes with better labels
|
||||
MS[Memory Service]
|
||||
ES[Entity Service]
|
||||
RS[Relation Service]
|
||||
FIO[File IO Module]
|
||||
DB[(SQLite DB)]
|
||||
Files[Markdown Files]
|
||||
SW[Semantic Web]
|
||||
MP[Memory Protocol]
|
||||
URI[memory:// URIs]
|
||||
|
||||
%% Core service relationships
|
||||
MS --> ES
|
||||
MS --> RS
|
||||
MS --> FIO
|
||||
|
||||
%% Storage connections
|
||||
ES --> DB
|
||||
RS --> DB
|
||||
FIO --> Files
|
||||
|
||||
%% Knowledge layer relationships
|
||||
SW --> MP
|
||||
MP --> URI
|
||||
URI --> MS
|
||||
|
||||
%% Group related components
|
||||
subgraph "Knowledge Layer"
|
||||
SW
|
||||
MP
|
||||
URI
|
||||
end
|
||||
|
||||
subgraph "Core Services"
|
||||
MS
|
||||
ES
|
||||
RS
|
||||
FIO
|
||||
end
|
||||
|
||||
subgraph "Storage"
|
||||
DB
|
||||
Files
|
||||
end
|
||||
|
||||
%% Style definitions
|
||||
classDef default fill:#2d2d2d,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
|
||||
classDef storage fill:#404040,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
|
||||
classDef knowledge fill:#353535,stroke:#d4d4d4,stroke-width:2px,color:#d4d4d4
|
||||
|
||||
%% Apply styles
|
||||
class DB,Files storage
|
||||
class SW,MP,URI knowledge
|
||||
```
|
||||
|
||||
## Obsidian Integration: The Human Interface
|
||||
|
||||
### Visual Knowledge Navigation
|
||||
Obsidian provides:
|
||||
- Interactive graph visualization
|
||||
- Wiki-style navigation
|
||||
- Familiar markdown editing
|
||||
- Full-text search
|
||||
|
||||
### Two-Way Sync
|
||||
- Files editable in Obsidian or programmatically
|
||||
- Database stays in sync with files
|
||||
- Changes propagate automatically
|
||||
- History preserved through git
|
||||
|
||||
### Knowledge Graph with Relations
|
||||
|
||||
```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
|
||||
|
||||
%% 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
|
||||
```
|
||||
---
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
## Knowledge Representation
|
||||
|
||||
### Entity Document Example
|
||||
```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.
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
### Auto-Generated Index Example
|
||||
```markdown
|
||||
---
|
||||
type: index
|
||||
indexType: technical_components
|
||||
generated: 2024-12-10T17:00:00Z
|
||||
autoUpdate: true
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
## Coming Soon
|
||||
- Obsidian compatibility layer
|
||||
- Enhanced navigation features
|
||||
- Improved AI context building
|
||||
- CLI tool suite for managing AI sync
|
||||
|
||||
## 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
|
||||
@@ -1,66 +0,0 @@
|
||||
|
||||
## How we work
|
||||
|
||||
We usually work like this:
|
||||
* We talk about ideas
|
||||
* Most of the time you write the files locally
|
||||
* I review them in my IDE
|
||||
* I run tests
|
||||
* We make changes and iterate
|
||||
* When things work, I commit changes again and we move on.
|
||||
|
||||
A few things about writing files
|
||||
* files have to be complete, no "# rest is the same", otherwise we lose file info
|
||||
* read files before writing, in case I've made changes locally
|
||||
* write files one at a time in chat responses, long responses can get truncated
|
||||
* We should break up large files into smaller ones so they are easier for you to update.
|
||||
|
||||
Collaboration
|
||||
* I want your 100% honest feedback
|
||||
* We work better together. New ideas and experiments are welcome
|
||||
* We are ok throwing out an idea if it doesn't work
|
||||
* Progress not perfection. We iterate slowly and build on what is working.
|
||||
* We've been moving fast, but now we have to focus on robust testing.
|
||||
* You update our project knowledge as we go
|
||||
|
||||
## Tools
|
||||
|
||||
We are dogfooding our basic-memory tool. You can use it to read from our knowledge graph and write new info.
|
||||
|
||||
## Project info
|
||||
|
||||
Base dir for `basic-memory` project knowledge: `/Users/phernandez/.basic-memory/projects/default`
|
||||
- you have access to the directory via the `files_system` tools
|
||||
|
||||
Files
|
||||
/Users/phernandez/.basic-memory/projects/default/entities/*
|
||||
|
||||
|
||||
db:
|
||||
/Users/phernandez/.basic-memory/projects/default/data/memory.db
|
||||
|
||||
- you have access to the db via the `sqlite` tool
|
||||
|
||||
## Code repo
|
||||
|
||||
Repo: /Users/phernandez/dev/basicmachines/basic-memory
|
||||
|
||||
```text
|
||||
(.venv) ➜ basic-memory git:(main) ✗ tree -d
|
||||
.
|
||||
├── db
|
||||
│ └── migrations
|
||||
├── docs
|
||||
├── examples
|
||||
├── projects
|
||||
│ └── obsidian
|
||||
├── src
|
||||
│ └── basic_memory
|
||||
│ ├── cli
|
||||
│ ├── mcp
|
||||
│ ├── repository
|
||||
│ └── services
|
||||
└── tests
|
||||
|
||||
|
||||
```
|
||||
@@ -1,67 +0,0 @@
|
||||
"""Script to migrate entity files into type-based folders."""
|
||||
import re
|
||||
import asyncio
|
||||
from pathlib import Path
|
||||
|
||||
from basic_memory.models import Entity
|
||||
|
||||
async def migrate_files(entities_path: Path):
|
||||
"""Move entity files into type-based directories."""
|
||||
|
||||
# Get all markdown files
|
||||
files = list(entities_path.glob("*.md"))
|
||||
print(f"Found {len(files)} markdown files")
|
||||
|
||||
# Track progress
|
||||
moved = []
|
||||
errors = []
|
||||
|
||||
for file in files:
|
||||
try:
|
||||
# Read file
|
||||
content = file.read_text()
|
||||
|
||||
# Extract type using regex
|
||||
type_match = re.search(r'^type:\s*(.+?)$', content, re.MULTILINE)
|
||||
if not type_match:
|
||||
errors.append((file, "No type found"))
|
||||
continue
|
||||
|
||||
entity_type = type_match.group(1).strip()
|
||||
|
||||
# Create type directory
|
||||
type_dir = entities_path / entity_type
|
||||
type_dir.mkdir(exist_ok=True)
|
||||
|
||||
# Move the file
|
||||
new_path = type_dir / file.name
|
||||
file.rename(new_path)
|
||||
|
||||
moved.append((file, new_path))
|
||||
print(f"Moved {file.name} to {entity_type}/")
|
||||
|
||||
except Exception as e:
|
||||
errors.append((file, str(e)))
|
||||
print(f"Error processing {file}: {e}")
|
||||
|
||||
# Print summary
|
||||
print("\nMigration complete!")
|
||||
print(f"Successfully moved: {len(moved)}")
|
||||
if errors:
|
||||
print("\nErrors:")
|
||||
for file, error in errors:
|
||||
print(f" {file.name}: {error}")
|
||||
|
||||
if __name__ == "__main__":
|
||||
import sys
|
||||
|
||||
if len(sys.argv) != 2:
|
||||
print("Usage: python migrate_to_folders.py <entities_path>")
|
||||
sys.exit(1)
|
||||
|
||||
entities_path = Path(sys.argv[1])
|
||||
if not entities_path.exists():
|
||||
print(f"Entities directory not found: {entities_path}")
|
||||
sys.exit(1)
|
||||
|
||||
asyncio.run(migrate_files(entities_path))
|
||||
Reference in New Issue
Block a user