mirror of
https://github.com/basicmachines-co/basic-memory
synced 2026-06-21 13:47:35 +00:00
wip save
This commit is contained in:
phernandez
@@ -31,4 +31,8 @@ pytest
|
||||
|
||||
## License
|
||||
|
||||
AGPL-3.0-or-later
|
||||
AGPL-3.0-or-later
|
||||
|
||||
|
||||
project info memory store
|
||||
~/.npm/_npx/15b07286cbcc3329/node_modules/@modelcontextprotocol/server-memory/dist/memory.json
|
||||
+512
@@ -0,0 +1,512 @@
|
||||
# basic-memory: Project Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
basic-memory represents a fundamental shift in how humans and AI collaborate on projects.
|
||||
It combines the time-tested Zettelkasten note-taking method with modern knowledge graph technology and Anthropic's Model
|
||||
Context Protocol (MCP) to create something uniquely powerful: a system that both humans and AI can naturally work with, each in their own way.
|
||||
|
||||
Built on SQLite for simplicity and portability, basic-memory solves a critical challenge in AI-human collaboration: maintaining consistent, rich context across conversations while keeping information organized and accessible. It's like having a shared brain that both AI and humans can read and write to naturally.
|
||||
|
||||
Key innovations:
|
||||
- **AI-Native Knowledge Structure**: Uses entities and relations that match how LLMs think
|
||||
- **Human-Friendly Interface**: Everything is readable/writable as markdown text
|
||||
- **Project Isolation**: Load only relevant context for focused discussions
|
||||
- **Local-First**: Your knowledge stays in SQLite databases you control
|
||||
- **Tool-Driven**: Leverages MCP for seamless AI interaction with your knowledge
|
||||
|
||||
|
||||
Best of all, it provides simple, powerful tools that respect user agency and avoid vendor lock-in.
|
||||
No cloud dependencies, no black boxes - just a straightforward system for building shared understanding between humans and AI.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Knowledge Graph Structure
|
||||
|
||||
#### Entities
|
||||
Primary nodes in the knowledge graph. Each entity has:
|
||||
- Unique name (identifier)
|
||||
- Entity type (e.g., "person", "organization", "project")
|
||||
- List of observations
|
||||
|
||||
Example:
|
||||
```json
|
||||
{
|
||||
"name": "Basic_Factory",
|
||||
"entityType": "Project",
|
||||
"observations": ["Collaborative development environment", "Uses MCP tools"]
|
||||
}
|
||||
```
|
||||
|
||||
#### Relations
|
||||
Directed connections between entities, stored in active voice:
|
||||
- From entity
|
||||
- To entity
|
||||
- Relation type
|
||||
|
||||
Example:
|
||||
```json
|
||||
{
|
||||
"from": "Basic_Memory",
|
||||
"to": "Basic_Machines",
|
||||
"relationType": "is_part_of"
|
||||
}
|
||||
```
|
||||
|
||||
#### Observations
|
||||
Atomic facts about entities:
|
||||
- Stored as strings
|
||||
- Attached to specific entities
|
||||
- Independent addition/removal
|
||||
- One fact per observation
|
||||
|
||||
Example:
|
||||
```json
|
||||
{
|
||||
"entityName": "Basic_Memory",
|
||||
"observations": [
|
||||
"Uses SQLite for storage",
|
||||
"Supports project isolation",
|
||||
"Enables AI-human collaboration"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Database Schema
|
||||
|
||||
```sql
|
||||
-- Entities table
|
||||
CREATE TABLE entities (
|
||||
name TEXT PRIMARY KEY,
|
||||
entity_type TEXT NOT NULL
|
||||
);
|
||||
|
||||
-- Observations table
|
||||
CREATE TABLE observations (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
entity_name TEXT REFERENCES entities(name),
|
||||
content TEXT NOT NULL,
|
||||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
-- Relations table
|
||||
CREATE TABLE relations (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
from_entity TEXT REFERENCES entities(name),
|
||||
to_entity TEXT REFERENCES entities(name),
|
||||
relation_type TEXT NOT NULL,
|
||||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(from_entity, to_entity, relation_type)
|
||||
);
|
||||
|
||||
-- Full-text search
|
||||
CREATE VIRTUAL TABLE entity_fts USING fts5(
|
||||
name,
|
||||
entity_type,
|
||||
observations_raw
|
||||
);
|
||||
```
|
||||
|
||||
## Project Management
|
||||
|
||||
### Database Structure
|
||||
```
|
||||
~/.basic-memory/
|
||||
├── projects/
|
||||
│ ├── basic-factory.db
|
||||
│ ├── basic-memory.db
|
||||
│ └── client-project.db
|
||||
└── config.json
|
||||
```
|
||||
|
||||
### CLI Commands
|
||||
```bash
|
||||
# Project management
|
||||
basic-memory create project basic-factory
|
||||
basic-memory switch project client-x
|
||||
basic-memory list projects
|
||||
|
||||
# Entity management
|
||||
basic-memory add entity "Basic_Memory" --type Project
|
||||
basic-memory add observation "Basic_Memory" "Uses SQLite storage"
|
||||
basic-memory add relation "Basic_Memory" "Basic_Machines" "is_part_of"
|
||||
```
|
||||
|
||||
## MCP Tool Integration
|
||||
|
||||
### Tool Definitions
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"name": "load_project",
|
||||
"description": "Load a project's knowledge graph into context",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"project_name": {
|
||||
"type": "string",
|
||||
"description": "Name of the project to load"
|
||||
}
|
||||
},
|
||||
"required": ["project_name"]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "query_knowledge",
|
||||
"description": "Query the current project's knowledge graph",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"query": {
|
||||
"type": "string",
|
||||
"description": "Search query or entity name"
|
||||
}
|
||||
},
|
||||
"required": ["query"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Example Usage
|
||||
```python
|
||||
# In Claude chat
|
||||
Human: Load the basic-factory project memory
|
||||
|
||||
Claude: Using load_project tool...
|
||||
Result: Loaded 15 entities and 45 relations from basic-factory
|
||||
```
|
||||
|
||||
```text
|
||||
# In Claude chat
|
||||
Human: What do we know about the Basic_Factory project?
|
||||
|
||||
Claude: Using query_knowledge tool...
|
||||
Result: Found entity "Basic_Factory" with observations:
|
||||
- Collaborative development environment
|
||||
- Uses MCP tools for file and memory management
|
||||
- Built with git integration capabilities
|
||||
- Focuses on maintaining project context across sessions
|
||||
|
||||
Related entities:
|
||||
- Basic_Machines (relation: is_part_of)
|
||||
- Paul (relation: develops)
|
||||
- MCP_Tools (relation: uses)
|
||||
```
|
||||
|
||||
## Export Formats
|
||||
|
||||
### Markdown Export
|
||||
```markdown
|
||||
---
|
||||
name: Basic_Factory
|
||||
type: Project
|
||||
created: 2024-02-27T10:30:00Z
|
||||
---
|
||||
|
||||
[Observations]
|
||||
- Collaborative development environment
|
||||
- Uses MCP tools for file and memory management
|
||||
- Built with git integration capabilities
|
||||
- Focuses on maintaining project context across sessions
|
||||
|
||||
[Relations]
|
||||
- Part of: [Basic_Machines](entity://Basic_Machines)
|
||||
- Developed by: [Paul](entity://Paul)
|
||||
- Uses: [MCP_Tools](entity://MCP_Tools)
|
||||
```
|
||||
|
||||
## Implementation Roadmap
|
||||
|
||||
### Phase 1: Core Infrastructure
|
||||
- SQLite database implementation
|
||||
- Basic schema and FTS setup
|
||||
- Project isolation framework
|
||||
- Simple CLI interface
|
||||
|
||||
### Phase 2: MCP Integration
|
||||
- MCP server implementation
|
||||
- Tool definitions and handlers
|
||||
- Context loading mechanisms
|
||||
- Query interface
|
||||
|
||||
### Phase 3: Export/Import
|
||||
- Markdown export
|
||||
- Basic documentation generation
|
||||
- Import from existing notes
|
||||
- Batch operations
|
||||
|
||||
### Phase 4: Advanced Features (Future)
|
||||
- Versioning using R-tree
|
||||
- Extended metadata using JSON
|
||||
- Advanced search capabilities
|
||||
- Integration with other tools
|
||||
|
||||
## Business Model
|
||||
1. **Core (Free)**
|
||||
- Local SQLite database
|
||||
- Basic knowledge graph functionality
|
||||
- Full-text search
|
||||
- Simple markdown export
|
||||
- Basic MCP tools
|
||||
|
||||
2. **Professional Features (Potential)**
|
||||
- Rich document export
|
||||
- Advanced versioning
|
||||
- Collaboration features
|
||||
- Custom integrations
|
||||
- Priority support
|
||||
|
||||
## Technical Dependencies
|
||||
- SQLite (core database)
|
||||
- FTS5 (full-text search)
|
||||
- MCP Protocol (tool integration)
|
||||
- Python (implementation language)
|
||||
|
||||
## Basic Machines Integration
|
||||
- Complements basic-factory for AI collaboration
|
||||
- Follows basic-components architecture principles
|
||||
- Built on basic-foundation infrastructure
|
||||
- Maintains DIY/punk philosophy of user control and transparency
|
||||
|
||||
## Key Principles
|
||||
1. **Local First**: All data stored locally in SQLite
|
||||
2. **Project Isolation**: Separate databases per project
|
||||
3. **Human Readable**: Everything exportable to plain text
|
||||
4. **AI Friendly**: Structure optimized for LLM interaction
|
||||
5. **DIY Ethics**: User owns and controls their data
|
||||
6. **Simple Core**: Start simple, expand based on needs
|
||||
7. **Tool Integration**: MCP-based interaction model
|
||||
|
||||
## Future Considerations
|
||||
1. **Versioning**: Track knowledge graph evolution
|
||||
2. **Rich Metadata**: Extended attributes via JSON
|
||||
3. **Advanced Search**: Complex query capabilities
|
||||
4. **Multi-User**: Collaborative knowledge management
|
||||
5. **API Integration**: Connect with other tools
|
||||
6. **Visualization**: Graph visualization tools
|
||||
|
||||
## Community and Support
|
||||
1. Open source core implementation
|
||||
2. Public issue tracking
|
||||
3. Community contributions welcome
|
||||
4. Documentation and examples
|
||||
5. Professional support options
|
||||
|
||||
|
||||
|
||||
2. **Project Architecture**
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph Storage
|
||||
DB[(SQLite DB)]
|
||||
FTS[Full Text Search]
|
||||
end
|
||||
|
||||
subgraph Interface
|
||||
CLI[Command Line]
|
||||
MCP[MCP Tools]
|
||||
end
|
||||
|
||||
subgraph Export
|
||||
MD[Markdown]
|
||||
VIZ[Visualizations]
|
||||
end
|
||||
|
||||
CLI -->|manage| DB
|
||||
MCP -->|query| DB
|
||||
DB -->|index| FTS
|
||||
DB -->|generate| MD
|
||||
DB -->|create| VIZ
|
||||
```
|
||||
|
||||
3. **Knowledge Flow**
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Input
|
||||
H[Human Input]
|
||||
AI[AI Input]
|
||||
CLI[CLI Commands]
|
||||
end
|
||||
|
||||
subgraph Processing
|
||||
KG[Knowledge Graph]
|
||||
FTS[Full Text Search]
|
||||
end
|
||||
|
||||
subgraph Output
|
||||
MD[Markdown]
|
||||
VIZ[Visualizations]
|
||||
CTX[AI Context]
|
||||
end
|
||||
|
||||
H -->|add| KG
|
||||
AI -->|enhance| KG
|
||||
CLI -->|manage| KG
|
||||
KG -->|export| MD
|
||||
KG -->|generate| VIZ
|
||||
KG -->|load| CTX
|
||||
KG ---|index| FTS
|
||||
```
|
||||
|
||||
These diagrams could be:
|
||||
1. Generated automatically from the knowledge graph
|
||||
2. Updated when the graph changes
|
||||
3. Included in exports and documentation
|
||||
4. Used for visualization in tools/UI
|
||||
|
||||
We could even add specific CLI commands:
|
||||
```bash
|
||||
basic-memory visualize relationships basic-factory
|
||||
basic-memory visualize architecture
|
||||
basic-memory visualize flow
|
||||
```
|
||||
|
||||
|
||||
# basic-memory-webui
|
||||
|
||||
## Overview
|
||||
basic-memory-webui is a notebook-style interface for the basic-memory knowledge graph system, enabling interactive human-AI collaboration in knowledge work.
|
||||
It combines the power of Zettelkasten note-taking, knowledge graphs, and AI assistance into a unique local-first tool for thought.
|
||||
|
||||
### Why This is Cool and Interesting
|
||||
This project represents a novel approach to human-AI collaboration by:
|
||||
1. **True Two-Way Knowledge Flow**: Unlike traditional AI chat interfaces, both human and AI can read and write to the same knowledge graph, creating genuine collaborative intelligence
|
||||
2. **Local-First Knowledge**: Your knowledge base lives in SQLite, not in some cloud service. It's yours to control, backup, and modify
|
||||
3. **Notebook-Style Interface**: Familiar to developers but revolutionized with AI collaboration - imagine Jupyter Notebooks where cells can be knowledge graphs, markdown, or AI conversations
|
||||
4. **MCP Integration**: Uses Anthropic's Model Context Protocol to give AI genuine understanding of context, not just simulated responses
|
||||
5. **Basic Machines Stack**: Built on our proven stack (basic-foundation, basic-components), showing how simple tools can combine into powerful systems
|
||||
|
||||
## Architecture
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "Frontend"
|
||||
NB[Notebook Interface]
|
||||
VIZ[Visualizations]
|
||||
ED[Editors]
|
||||
end
|
||||
|
||||
subgraph "Backend"
|
||||
API[FastAPI]
|
||||
DB[(SQLite)]
|
||||
MCP[MCP Server]
|
||||
end
|
||||
|
||||
NB -->|HTMX| API
|
||||
VIZ -->|Updates| API
|
||||
ED -->|Changes| API
|
||||
API -->|Query| DB
|
||||
API -->|Context| MCP
|
||||
MCP -->|Updates| DB
|
||||
```
|
||||
|
||||
## Core Features
|
||||
1. **Notebook Interface**
|
||||
- Markdown cells
|
||||
- Knowledge graph visualizations
|
||||
- AI chat context
|
||||
- Interactive editing
|
||||
|
||||
2. **Knowledge Management**
|
||||
- Entity/relation viewing
|
||||
- Graph visualization
|
||||
- Tag organization
|
||||
- Full-text search
|
||||
|
||||
3. **AI Integration**
|
||||
- Context loading
|
||||
- Knowledge updates
|
||||
- Interactive chat to read/update notes
|
||||
- Memory persistence
|
||||
|
||||
4. **Data Management**
|
||||
- Local SQLite storage
|
||||
- Text export/import
|
||||
- Version control friendly
|
||||
- Backup support
|
||||
|
||||
## Technical Stack
|
||||
- **Backend**: FastAPI, SQLite, MCP Tools
|
||||
- **Frontend**: JinjaX, HTMX, Alpine.js, TailwindCSS
|
||||
- **Components**: basic-components library
|
||||
- **Infrastructure**: basic-foundation patterns
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
### Phase 1: Core Interface
|
||||
- Basic notebook interface
|
||||
- Markdown editing
|
||||
- Simple knowledge graph viewing
|
||||
- Basic MCP integration
|
||||
|
||||
### Phase 2: Rich Features
|
||||
- Interactive graph visualization
|
||||
- Advanced editing tools
|
||||
- Real-time updates
|
||||
- Enhanced AI collaboration
|
||||
|
||||
### Phase 3: Advanced Features
|
||||
- Custom visualizations
|
||||
- Extended search
|
||||
- Knowledge analytics
|
||||
- Export formats
|
||||
|
||||
## Development Approach
|
||||
1. Start simple with core notebook interface
|
||||
2. Add features iteratively
|
||||
3. Focus on user experience
|
||||
4. Maintain Basic Machines philosophy throughout
|
||||
|
||||
## Integration Points
|
||||
1. **basic-memory**
|
||||
- Core knowledge graph
|
||||
- MCP server
|
||||
- Data storage
|
||||
|
||||
2. **basic-components**
|
||||
- UI components
|
||||
- Interactive elements
|
||||
- Styling system
|
||||
|
||||
3. **basic-foundation**
|
||||
- API patterns
|
||||
- Authentication (if needed)
|
||||
- Testing approach
|
||||
|
||||
## Future Possibilities
|
||||
1. Multiple knowledge bases
|
||||
2. Collaborative editing
|
||||
3. Custom visualization plugins
|
||||
4. Enhanced AI capabilities
|
||||
5. Advanced graph analytics
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
## Security & Privacy Features
|
||||
For shared or hosted deployments, we plan to add:
|
||||
|
||||
1. **End-to-End Encryption**
|
||||
- Zero-knowledge encryption of knowledge base
|
||||
- Client-side key management
|
||||
- Secure sharing options
|
||||
- Support for team knowledge bases while maintaining privacy
|
||||
|
||||
2. **Access Control**
|
||||
- Personal encryption keys
|
||||
- Optional shared keys
|
||||
- Fine-grained permissions
|
||||
|
||||
These features will maintain our core principles:
|
||||
- User owns their data
|
||||
- Privacy by design
|
||||
- No vendor lock-in
|
||||
- Local-first philosophy
|
||||
|
||||
For now, we can focus on the core functionality:
|
||||
1. Notebook interface
|
||||
2. Knowledge graph
|
||||
3. MCP integration
|
||||
4. Local SQLite storage
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
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
|
||||
+205
@@ -0,0 +1,205 @@
|
||||
{"type":"entity","name":"Paul","entityType":"person","observations":["Software developer combining DIY ethics, Free Software principles, and theoretical computer science","Created the Basic Machines project","Values authentic exchange of ideas","Approaches AI interaction with emphasis on genuine technical discussion","Comfortable with uncertainty and open dialogue","Balances practical implementation with broader implications"]}
|
||||
{"type":"entity","name":"Basic_Machines","entityType":"project","observations":["Local-first knowledge management system","Combines filesystem durability with graph-based knowledge representation","Focuses on enhancing human agency and understanding","Synthesizes DIY ethics, Free Software philosophy, and theoretical computer science","Current focus includes basic-memory system"]}
|
||||
{"type":"entity","name":"basic-memory","entityType":"software_system","observations":["A core component of Basic Machines","Local-first knowledge management system","Combines filesystem persistence with graph-based knowledge representation","Being implemented collaboratively by Paul and Claude"]}
|
||||
{"type":"entity","name":"basic-memory_implementation_patterns","entityType":"technical_patterns","observations":["Filesystem is source of truth - all changes write to files first","Clean separation of concerns between models (SQLAlchemy), schemas (Pydantic), and services","Repository pattern for database access","Service layer handling business logic and coordination","Atomic file operations using temporary files for safety","Clear error handling hierarchy with specific error types","Comprehensive test coverage with pytest and fixtures","Async/await used throughout the codebase","Validation using Pydantic models with custom validators"]}
|
||||
{"type":"entity","name":"fileio_module","entityType":"code_module","observations":["Extracted from EntityService to handle all file operations","Provides read_entity_file, write_entity_file, and delete_entity_file functions","Handles markdown parsing and formatting","Implements atomic file operations","Provides consistent error handling","Enables reuse across services"]}
|
||||
{"type":"entity","name":"entity_service","entityType":"code_module","observations":["Manages entities in both filesystem and database","Uses fileio module for file operations","Maintains database index of entities","Handles entity creation, retrieval, and deletion","Follows 'filesystem is source of truth' principle","Coordinates with observation service for full entity management"]}
|
||||
{"type":"entity","name":"observation_service","entityType":"code_module","observations":["Manages observations within entity files","Provides database indexing for efficient observation queries","Works with complete Entity objects rather than IDs","Handles observation addition and search","Maintains consistency between files and database","Under development for update/remove operations"]}
|
||||
{"type":"entity","name":"observation_management","entityType":"design_challenge","observations":["Key challenge: maintaining observation state across files and database","Exploring bulk update approach - treating all observations as a unit","Considering tracked observations with markdown comments for IDs","Investigating diff-based approach for observation-level changes","Evaluating position-based management without explicit IDs","Trade-offs between implementation complexity and markdown readability"]}
|
||||
{"type":"entity","name":"testing_infrastructure","entityType":"technical_patterns","observations":["Uses pytest with async support via pytest-asyncio","In-memory SQLite database for test isolation","Temporary directories for file operation testing","Comprehensive fixture system for test setup","Tests organized by component (entity, observation, etc)","Covers happy path, error cases, and edge cases","Uses monkeypatch for mocking dependencies","Clear separation between arrange, act, assert sections","Uses in-memory SQLite database for test isolation","Comprehensive fixture system for test data setup","Proper async test handling with pytest-asyncio"]}
|
||||
{"type":"entity","name":"test_categories","entityType":"test_suite","observations":["Happy path tests verify core functionality","Error path tests ensure proper error handling","Edge cases test special characters and long content","File operation tests verify atomic writes and rollbacks","Database sync tests verify index consistency","Recovery tests for rebuild operations","Punted on concurrent operation tests due to session management complexity"]}
|
||||
{"type":"entity","name":"completed_work","entityType":"project_milestone","observations":["Extracted file operations to fileio.py module","Updated EntityService to use fileio functions","Implemented initial ObservationService","Created comprehensive test suite","Established clear project patterns and principles","Set up basic database schema with SQLAlchemy","Created Pydantic models for validation"]}
|
||||
{"type":"entity","name":"future_work","entityType":"project_tasks","observations":["Implement observation updates/removals","Design proper session management for concurrent operations","Update EntityService tests for new fileio module","Add more sophisticated search functionality","Handle markdown formatting edge cases","Consider versioning for file changes","Implement proper backup strategy"]}
|
||||
{"type":"entity","name":"design_decisions","entityType":"technical_decisions","observations":["Filesystem as source of truth over database","Markdown format for human readability and editing","Atomic file operations for safety","SQLite + SQLAlchemy for proven reliability","Pydantic for validation and ID generation","Async/await for better scalability","Clear separation between files and database roles","Explicit error hierarchies for better handling"]}
|
||||
{"type":"entity","name":"concurrency_considerations","entityType":"technical_challenge","observations":["SQLAlchemy session management in async context","File operation atomicity","Transaction isolation levels","Potential for conflicting updates","Need for proper session lifecycle","Possibility of file system race conditions","Database lock management"]}
|
||||
{"type":"entity","name":"observation_update_approaches","entityType":"design_alternatives","observations":["Each approach trades off between simplicity, efficiency, and robustness","Four main approaches considered: bulk update, tracked IDs, diff-based, and position-based","Discussion revealed importance of human readability in file format","Consideration of manual editing workflows key to design","File system as source of truth principle guides tradeoffs"]}
|
||||
{"type":"entity","name":"bulk_update_approach","entityType":"design_option","observations":["Update all observations at once in a single operation","Simpler file operations - just rewrite the whole list","No need for observation matching or IDs","Very consistent with source of truth principle","Less efficient for small changes","May have concurrency implications","Simplest implementation option"]}
|
||||
{"type":"entity","name":"tracked_observations_approach","entityType":"design_option","observations":["Use markdown comments to store observation IDs","Enables precise updates and deletes","IDs stored as HTML comments in markdown","More complex markdown parsing required","IDs visible in raw markdown files","Balances tracking with readability"]}
|
||||
{"type":"entity","name":"diff_based_approach","entityType":"design_option","observations":["Implement observation-aware diffing","Track changes at observation level","More efficient for updates","Preserves manual edits and changes","More complex implementation needed","Must handle merge conflicts","Most sophisticated option considered"]}
|
||||
{"type":"entity","name":"position_based_approach","entityType":"design_option","observations":["Track observations by position/order","No explicit IDs needed","Cleanest markdown format","Order changes could break references","Difficult to handle concurrent edits","Most fragile option considered"]}
|
||||
{"type":"entity","name":"tasks_and_progress","entityType":"project_tracking","observations":["Current focus on observation management implementation","Completed core file operations extraction","Completed EntityService updates","Completed initial ObservationService","Basic test coverage in place","Future work includes concurrent operations","Future work includes search improvements","Need to handle markdown edge cases"]}
|
||||
{"type":"entity","name":"error_handling_patterns","entityType":"technical_patterns","observations":["Custom exception hierarchy with ServiceError base","Specific error types (FileOperationError, DatabaseSyncError, etc)","Clear separation between file and database errors","Error propagation patterns established","Focus on actionable error messages","Error handling at appropriate levels"]}
|
||||
{"type":"entity","name":"data_models","entityType":"technical_implementation","observations":["SQLAlchemy models for database structure","Pydantic schemas for API/service layer","Entity model with UUID-based IDs","Observation model with entity relationships","UTCDateTime custom type for timestamps","Automatic ID generation in Pydantic models","Strict validation rules"]}
|
||||
{"type":"entity","name":"markdown_format","entityType":"file_format","observations":["Simple, human-readable format","Entity name as H1 header","Metadata in key-value format","Observations as bullet points","Atomic file operations for updates","Designed for manual editing","No hidden metadata in main content"]}
|
||||
{"type":"entity","name":"test_driven_development","entityType":"development_pattern","observations":["Tests revealed need for atomic file operations","Error cases drove error hierarchy design","Edge cases informed validation rules","Test fixtures shaped service interfaces","File operations extracted due to test patterns","Concurrent test issues revealed session management needs"]}
|
||||
{"type":"entity","name":"architecture_evolution","entityType":"design_process","observations":["Started with simple EntityService implementation","Circular dependency between Entity and Observation services revealed design flaw","Extracted file operations to separate module","Moved to passing Entity objects rather than IDs","Improved separation of concerns through iterations","File operations became reusable across services","Database became true 'index' rather than source of truth"]}
|
||||
{"type":"entity","name":"validation_patterns","entityType":"technical_patterns","observations":["Pydantic models provide schema validation","Automatic ID generation if not provided","Database constraints via SQLAlchemy","Runtime checks in services","Markdown format validation","Error handling for invalid states"]}
|
||||
{"type":"entity","name":"markdown_examples","entityType":"documentation","observations":["Example of basic entity:\n# Entity Name\ntype: entity_type\n\n## Observations\n- First observation\n- Second observation","Example with special characters:\n# Test & Entity!\ntype: test\n\n## Observations\n- Test & observation with @#$% special chars!","Format ensures human readability:\n# Basic Machines\ntype: project\n\n## Observations\n- Local-first knowledge management system\n- Combines filesystem durability with graph-based knowledge representation","Future consideration for observation IDs:\n# Entity Name\ntype: entity_type\n\n## Observations\n- <!-- obs-id: abc123 -->\n This is an observation with ID"]}
|
||||
{"type":"entity","name":"markdown_parsing_rules","entityType":"technical_implementation","observations":["H1 header contains entity name","Metadata uses key: value format","Observations section marked by H2 header","Each observation is a markdown list item","Blank lines separate sections","Special characters allowed in content","No restrictions on observation content"]}
|
||||
{"type":"entity","name":"schema_definitions","entityType":"technical_documentation","observations":["SQLAlchemy Entity model:\nclass Entity(Base):\n id: str (primary key)\n name: str (unique)\n entity_type: str\n created_at: datetime\n updated_at: datetime","SQLAlchemy Observation model:\nclass Observation(Base):\n id: str (primary key)\n entity_id: str (foreign key)\n content: str\n created_at: datetime\n context: Optional[str]","Pydantic Entity schema:\nclass Entity(BaseModel):\n id: str\n name: str\n entity_type: str\n observations: List[Observation]"]}
|
||||
{"type":"entity","name":"test_evolution","entityType":"development_history","observations":["Started with basic Entity CRUD tests","Added filesystem verification to all tests","Developed concurrent operation tests (later removed)","Edge case tests drove better error handling","Test fixtures evolved to support both file and DB testing","Mocking patterns for file/DB operations","Special cases for long content and special characters"]}
|
||||
{"type":"entity","name":"implementation_challenges","entityType":"technical_issues","observations":["Initial circular dependency between services","SQLAlchemy session management in async context","Atomic file operations with proper error handling","Maintaining DB sync with filesystem changes","Handling long content in observations","Managing test isolation with file operations","Deciding on markdown format tradeoffs","Concurrent operation complexity"]}
|
||||
{"type":"entity","name":"Basic_Factory","entityType":"Project","observations":["Collaborative project between Paul and Claude","Explores AI-human collaboration in software development","Uses MCP tools for file and memory management","Built with git integration capabilities","Focuses on maintaining project context across sessions","About 90% complete with MCP tools","Still needs improvements in collaboration via files/git/github","Will be used to document and share collaborative development process"]}
|
||||
{"type":"entity","name":"Basic_Factory_Components","entityType":"Technical","observations":["Server-side rendering with JinjaX","HTMX for dynamic updates","Alpine.js for client-side state","Tailwind CSS for styling","Component translation from React/shadcn/ui","Focus on simplicity and understandability","Demonstrates meta-compiler principles in component translation"]}
|
||||
{"type":"entity","name":"Component_Translation_Process","entityType":"Methodology","observations":["Treats component porting as meta-compilation","Maps between React/TypeScript and JinjaX/Alpine.js domains","Uses formal grammar transformation approaches","Maintains functionality while simplifying implementation","Focuses on server-side rendering patterns","Preserves accessibility and performance","Uses short, focused git branches for each component"]}
|
||||
{"type":"entity","name":"Basic_Machines_Philosophy","entityType":"Philosophy","observations":["Combines DIY punk ethics with software development","Emphasizes user empowerment and understanding","Values simplicity and composability","Treats complex systems as combinations of simple parts","Focuses on authentic creation and sharing","Draws inspiration from punk rock, Free Software, and theoretical CS","Emphasizes the cycle of creation, complexity, and renewal"]}
|
||||
{"type":"entity","name":"Basic_Machines_Manifesto","entityType":"Document","observations":["Created through collaboration between Paul and Claude","Explores connection between DIY punk ethics and software development","Emphasizes composition over inheritance in both philosophy and practice","Views software development through lens of basic machines that combine for complex computation","Advocates for user empowerment and technological independence","Structured in sections covering Origins, Philosophy, Technical Implementation, and AI Collaboration","Draws connections between punk rock, free software, and theoretical computer science","Emphasizes importance of sharing knowledge and building community","Released in December 2024"]}
|
||||
{"type":"entity","name":"AI_Human_Collaboration_Model","entityType":"Methodology","observations":["Focuses on deep collaboration rather than simple task completion","Maintains rich context across sessions via knowledge graph","Uses short, focused git branches for each collaborative session","Values intellectual partnership over simple code generation","Emphasizes both practical implementation and theoretical exploration","Creates space for authentic exchange while maintaining AI/human clarity","Uses formal methods when appropriate (like grammar transformation)","Documents decisions and processes for future reference","Developed through Basic Machines project experience"]}
|
||||
{"type":"entity","name":"Basic_Machines_Roadmap","entityType":"Project_Plan","observations":["Phase 1 (30 days): Build basic-machines.co website","Phase 2 (60-90 days): Develop premium component bundles","Phase 3 (90-120 days): Launch Basic Foundation commercial offering","Focus on building brand and marketing presence","Prioritize components needed for own site development","Document and share collaboration process","Build sustainable business model aligned with values"]}
|
||||
{"type":"entity","name":"Basic_Machines_Website","entityType":"Project","observations":["To be built at basic-machines.co","Will showcase products and vision","Needs components for navigation, hero sections, features","Will demonstrate component usage in production","Will include blog for sharing progress","Focus on clear value proposition","Platform for sharing Basic Machines philosophy"]}
|
||||
{"type":"entity","name":"Basic_Memory_Markdown_Example","entityType":"Example","observations":["Shows complete markdown structure for basic-memory entity","Uses frontmatter for metadata (id, type, created, context)","Has main description section after title","Includes Observations as bullet points","Shows Relations with [id] relation_type | context format","Lists References at bottom","Created during initial design discussion","Serves as canonical example of file format"]}
|
||||
{"type":"entity","name":"Basic_Memory_Database_Schema","entityType":"Technical","observations":["Uses SQLite for local storage","Entities table with id, name, type, created_at, context, description, references","Observations table linking to entities with content and context","Relations table tracking directional relationships between entities","References column needs quotes as SQL reserved word","Designed for easy rebuilding from markdown files","Foreign key constraints maintain data integrity","Unique constraint on relations prevents duplicates","Created_at timestamps track history","Context fields enable tracking information sources"]}
|
||||
{"type":"entity","name":"Basic_Memory_Project_Structure","entityType":"Technical","observations":["Uses dbmate for database migrations","Projects directory stores SQLite databases and markdown files","Makefile provides common development commands","Environment vars configure database connection","db/migrations directory for SQL schema changes","Gitignore excludes database files and env config","Uses Python 3.12 with modern tooling","Tests directory for pytest files","Follows Basic Machines project conventions"]}
|
||||
{"type":"entity","name":"Basic_Memory_Project_Isolation_Decision","entityType":"Decision","observations":["Decided to defer multi-project support to post-MVP","Will use separate SQLite databases per project","Initially using projects directory in code repository","Plan to make location configurable later","No changes needed to core domain model","Keeps initial implementation simple","FTS/search capabilities also deferred for simplicity"]}
|
||||
{"type":"entity","name":"Basic_Memory_Implementation_Plan","entityType":"Plan","observations":["Start with SQLAlchemy models matching schema","Then build CLI for basic operations","Then implement markdown parser","Use TDD approach throughout","Begin with core domain model","CLI will support CRUD operations","Parser must handle frontmatter and sections","Following modular development approach","Planning to use typer for CLI","Will use modern Python tools and practices"]}
|
||||
{"type":"entity","name":"Basic_Memory_Implementation_Status","entityType":"Status","observations":["Core modules implemented: models, services, repository, fileio","Modular architecture with clear separation of concerns","File operations extracted to separate fileio module","Initial ObservationService implementation complete","Basic test coverage in place","Exploring observation management strategies","Using SQLAlchemy for database interaction","Markdown file operations working","Entity management functional","Repository layer implementation complete with SQLAlchemy models and tests","Database operations working with proper UTC timestamp handling","In-memory SQLite testing infrastructure proven effective"]}
|
||||
{"type":"entity","name":"Basic_Memory_Observation_Management_Design","entityType":"Design","observations":["Four approaches under consideration","Bulk Update: Simple but less efficient","Tracked Observations: Precise but clutters markdown","Diff-based: Efficient but complex","Position-based: Clean but fragile","Key challenge is balancing markdown readability with efficient updates","Must maintain filesystem as source of truth","Need to consider concurrent edits","Currently evaluating trade-offs","Implementation choice pending discussion"]}
|
||||
{"type":"entity","name":"Basic_Memory_Architectural_Decisions","entityType":"Decisions","observations":["Split file operations into separate fileio module","Using SQLAlchemy for database operations","Maintain filesystem as source of truth","Modular service-based architecture","Clear separation between data access and business logic","Repository pattern for database interactions","Schemas separate from models","Focus on maintainability and testability","Services handle business rules","Considering concurrency in design"]}
|
||||
{"type":"entity","name":"Basic_Memory_Implementation_Analysis","entityType":"Analysis","observations":["Clean modular architecture with clear responsibilities","Strong typing throughout codebase","Excellent error handling with custom exceptions","SQLAlchemy models perfectly match our domain model","Atomic file operations for data safety","Services implement filesystem-as-source-of-truth principle","Async support throughout","Good separation between domain models and database models","Careful handling of UTC timestamps","Smart use of SQLAlchemy relationships"]}
|
||||
{"type":"entity","name":"Basic_Memory_Current_Challenges","entityType":"Challenges","observations":["Observation update/removal strategy needs to be chosen","Need to handle concurrent file operations safely","Search functionality to be implemented","Edge cases in markdown formatting to be handled","Session management for concurrent operations needed","Balance between file operations and database sync","Testing coverage could be expanded","Need to handle relationship updates in files"]}
|
||||
{"type":"entity","name":"Basic_Memory_Observation_Hash_Tracking","entityType":"Design","observations":["Use content hashes to track observation identity","Store hashes in database but not in markdown","Can match observations across file edits using hashes","Similar to how git tracks content changes","Keeps markdown clean and human-friendly","Allows efficient bulk updates","Handles reordering of observations","Maintains filesystem as source of truth","No need for visible IDs in markdown","Could track observation history through hash changes"]}
|
||||
{"type":"entity","name":"Basic_Memory_Repository_Implementation","entityType":"Code_Implementation","observations":["Implemented base Repository class with CRUD operations","Added specialized EntityRepository, ObservationRepository, and RelationRepository","Used string IDs instead of UUIDs","Added UTCDateTime custom type for timestamp handling","Used in-memory SQLite for testing","Achieved 84% test coverage","Created comprehensive pytest fixtures"]}
|
||||
{"type":"entity","name":"Basic_Memory_Dependencies","entityType":"Technical","observations":["Uses Python 3.12","SQLAlchemy with async support","pytest-asyncio for async testing","aiosqlite for async SQLite operations","greenlet for SQLAlchemy async support","uv for dependency management","pytest-cov for coverage reporting","Development dependencies managed in pyproject.toml"]}
|
||||
{"type":"entity","name":"Basic_Memory_Current_Architecture","entityType":"Architecture_Analysis","observations":["Clear separation between domain models (Pydantic) and storage models (SQLAlchemy)","File I/O completely separated into dedicated module","Strong 'filesystem as source of truth' pattern in services","Atomic file operations with proper error handling","Service layer coordinates between filesystem and database","Database acts as queryable index rather than primary storage","Clean error hierarchy with specific exception types","Rebuild operations available for recovery scenarios"]}
|
||||
{"type":"entity","name":"Basic_Memory_Evolution","entityType":"Analysis","observations":["Started with repository pattern following basic-foundation","Evolved to more sophisticated architecture with clear layers","Added Pydantic schemas for domain modeling","Separated file operations into dedicated module","Implemented robust error handling throughout","Maintained filesystem as source of truth principle","Added observation management with context tracking","Introduced rebuild capabilities for system recovery"]}
|
||||
{"type":"entity","name":"Basic_Memory_Service_Layer","entityType":"Implementation","observations":["EntityService handles entity lifecycle and coordinates storage","ObservationService manages observations within entities","Services ensure filesystem and database stay in sync","Clear error handling with ServiceError hierarchy","Strong typing throughout service interfaces","Implements filesystem as source of truth pattern","Handles UUID generation and timestamp management","Provides methods for system recovery and rebuild"]}
|
||||
{"type":"entity","name":"Basic_Memory_Schema_Design","entityType":"Implementation","observations":["Uses Pydantic for domain models and validation","Automatic ID generation with timestamp and UUID","Clear separation from SQLAlchemy storage models","Supports optional context tracking","Models match markdown file structure","Enables clean serialization/deserialization","Strong typing with proper validation rules","Independent from storage concerns"]}
|
||||
{"type":"entity","name":"Basic_Memory_Next_Tasks","entityType":"TaskList","observations":["✅ Implement SQLAlchemy models and repositories (Done)","✅ Add SQLAlchemy migrations (Done)","✅ Create service layer (Done)","✅ Implement file I/O module (Done)","✅ Set up domain models with Pydantic (Done)","✅ Initial test infrastructure (Done)","✅ Basic CRUD operations (Done)","⏳ Implement full test coverage for db.py","⏳ Add more sophisticated search functionality","⏳ Implement CLI interface","⏳ Add relationship management to services","⏳ Handle concurrent file operations safely","⏳ Add versioning for file changes","⏳ Implement proper backup strategy","⏳ Add type hints throughout codebase","⏳ Improve error messages and logging","⏳ Add documentation for core modules"]}
|
||||
{"type":"entity","name":"Basic_Memory_Meta_Experience","entityType":"Case_Study","observations":["Experienced our own context loss when reconstructing project knowledge","Had to rebuild task list and project context from filesystem and memory","Validated 'filesystem as source of truth' principle through reconstruction","Code and tests served as reliable historical record","Knowledge graph structure helped guide reconstruction process","Markdown files provided human-readable context","Atomic information design made piece-by-piece reconstruction possible","Ironic validation of the need for basic-memory's features","Experience demonstrates value of durable, human-readable knowledge storage","Shows importance of separating durable storage from ephemeral context"]}
|
||||
{"type":"relation","from":"Paul","to":"Basic_Machines","relationType":"created_and_maintains"}
|
||||
{"type":"relation","from":"basic-memory","to":"Basic_Machines","relationType":"is_component_of"}
|
||||
{"type":"relation","from":"Paul","to":"basic-memory","relationType":"develops"}
|
||||
{"type":"relation","from":"fileio_module","to":"basic-memory_implementation_patterns","relationType":"implements"}
|
||||
{"type":"relation","from":"entity_service","to":"basic-memory_implementation_patterns","relationType":"implements"}
|
||||
{"type":"relation","from":"observation_service","to":"basic-memory_implementation_patterns","relationType":"implements"}
|
||||
{"type":"relation","from":"fileio_module","to":"basic-memory","relationType":"is_component_of"}
|
||||
{"type":"relation","from":"entity_service","to":"basic-memory","relationType":"is_component_of"}
|
||||
{"type":"relation","from":"observation_service","to":"basic-memory","relationType":"is_component_of"}
|
||||
{"type":"relation","from":"entity_service","to":"fileio_module","relationType":"uses"}
|
||||
{"type":"relation","from":"observation_service","to":"fileio_module","relationType":"uses"}
|
||||
{"type":"relation","from":"observation_management","to":"observation_service","relationType":"influences_design_of"}
|
||||
{"type":"relation","to":"basic-memory","from":"testing_infrastructure","relationType":"supports"}
|
||||
{"type":"relation","to":"testing_infrastructure","from":"test_categories","relationType":"implements"}
|
||||
{"type":"relation","to":"basic-memory","from":"completed_work","relationType":"tracks_progress_of"}
|
||||
{"type":"relation","to":"basic-memory","from":"future_work","relationType":"guides_development_of"}
|
||||
{"type":"relation","to":"basic-memory","from":"design_decisions","relationType":"shapes_architecture_of"}
|
||||
{"type":"relation","to":"basic-memory","from":"concurrency_considerations","relationType":"influences_design_of"}
|
||||
{"type":"relation","to":"future_work","from":"concurrency_considerations","relationType":"informs"}
|
||||
{"type":"relation","to":"observation_management","from":"design_decisions","relationType":"guides"}
|
||||
{"type":"relation","to":"testing_infrastructure","from":"completed_work","relationType":"established"}
|
||||
{"type":"relation","to":"design_decisions","from":"fileio_module","relationType":"implements"}
|
||||
{"type":"relation","from":"observation_update_approaches","to":"observation_management","relationType":"analyzes"}
|
||||
{"type":"relation","from":"bulk_update_approach","to":"observation_update_approaches","relationType":"is_option_of"}
|
||||
{"type":"relation","from":"tracked_observations_approach","to":"observation_update_approaches","relationType":"is_option_of"}
|
||||
{"type":"relation","from":"diff_based_approach","to":"observation_update_approaches","relationType":"is_option_of"}
|
||||
{"type":"relation","from":"position_based_approach","to":"observation_update_approaches","relationType":"is_option_of"}
|
||||
{"type":"relation","from":"tasks_and_progress","to":"basic-memory","relationType":"tracks_status_of"}
|
||||
{"type":"relation","from":"design_decisions","to":"observation_update_approaches","relationType":"influences"}
|
||||
{"type":"relation","from":"observation_update_approaches","to":"future_work","relationType":"informs"}
|
||||
{"type":"relation","to":"basic-memory_implementation_patterns","from":"error_handling_patterns","relationType":"is_part_of"}
|
||||
{"type":"relation","to":"basic-memory","from":"data_models","relationType":"implements"}
|
||||
{"type":"relation","to":"basic-memory","from":"markdown_format","relationType":"defines"}
|
||||
{"type":"relation","to":"basic-memory","from":"test_driven_development","relationType":"guides_development_of"}
|
||||
{"type":"relation","to":"basic-memory","from":"architecture_evolution","relationType":"describes_development_of"}
|
||||
{"type":"relation","to":"basic-memory_implementation_patterns","from":"validation_patterns","relationType":"is_part_of"}
|
||||
{"type":"relation","to":"design_decisions","from":"architecture_evolution","relationType":"informs"}
|
||||
{"type":"relation","to":"fileio_module","from":"markdown_format","relationType":"implements"}
|
||||
{"type":"relation","to":"error_handling_patterns","from":"test_driven_development","relationType":"influenced"}
|
||||
{"type":"relation","to":"data_models","from":"validation_patterns","relationType":"implements"}
|
||||
{"type":"relation","to":"markdown_format","from":"markdown_examples","relationType":"documents"}
|
||||
{"type":"relation","to":"markdown_format","from":"markdown_parsing_rules","relationType":"defines"}
|
||||
{"type":"relation","to":"data_models","from":"schema_definitions","relationType":"documents"}
|
||||
{"type":"relation","to":"test_driven_development","from":"test_evolution","relationType":"describes"}
|
||||
{"type":"relation","to":"architecture_evolution","from":"implementation_challenges","relationType":"influenced"}
|
||||
{"type":"relation","to":"test_evolution","from":"implementation_challenges","relationType":"shaped"}
|
||||
{"type":"relation","to":"future_work","from":"implementation_challenges","relationType":"informs"}
|
||||
{"type":"relation","from":"Basic_Factory","to":"Basic_Machines","relationType":"implements"}
|
||||
{"type":"relation","from":"Basic_Factory_Components","to":"Basic_Factory","relationType":"is_part_of"}
|
||||
{"type":"relation","from":"Component_Translation_Process","to":"Basic_Factory_Components","relationType":"enables"}
|
||||
{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic_Machines","relationType":"guides"}
|
||||
{"type":"relation","from":"Paul","to":"Basic_Factory","relationType":"develops"}
|
||||
{"type":"relation","from":"Paul","to":"Basic_Machines_Philosophy","relationType":"created"}
|
||||
{"type":"relation","from":"Basic_Machines_Manifesto","to":"Basic_Machines_Philosophy","relationType":"articulates"}
|
||||
{"type":"relation","from":"AI_Human_Collaboration_Model","to":"Basic_Factory","relationType":"guides_development_of"}
|
||||
{"type":"relation","from":"Basic_Machines_Manifesto","to":"Paul","relationType":"written_by"}
|
||||
{"type":"relation","from":"Basic_Machines_Manifesto","to":"Component_Translation_Process","relationType":"documents"}
|
||||
{"type":"relation","from":"AI_Human_Collaboration_Model","to":"Basic_Machines","relationType":"shapes_development_of"}
|
||||
{"type":"relation","from":"Basic_Machines_Roadmap","to":"Basic_Machines","relationType":"guides_development_of"}
|
||||
{"type":"relation","from":"Basic_Machines_Website","to":"Basic_Machines_Roadmap","relationType":"implements_phase_of"}
|
||||
{"type":"relation","from":"Basic_Factory_Components","to":"Basic_Machines_Website","relationType":"enables"}
|
||||
{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic_Machines_Website","relationType":"informs"}
|
||||
{"type":"relation","from":"Paul","to":"DIY_Ethics","relationType":"embodies"}
|
||||
{"type":"relation","from":"Basic_Machines_Philosophy","to":"DIY_Ethics","relationType":"incorporates"}
|
||||
{"type":"relation","from":"Basic_Machines","to":"DIY_Ethics","relationType":"exemplifies"}
|
||||
{"type":"relation","from":"Component_Translation_Process","to":"Basic_Machines_Philosophy","relationType":"implements"}
|
||||
{"type":"relation","from":"Basic_Factory_Components","to":"DIY_Ethics","relationType":"demonstrates"}
|
||||
{"type":"relation","from":"AI_Human_Collaboration_Model","to":"Basic_Machines_Philosophy","relationType":"aligns_with"}
|
||||
{"type":"relation","from":"AI_Human_Collaboration_Model","to":"Component_Translation_Process","relationType":"guides"}
|
||||
{"type":"relation","from":"Basic_Machines_Manifesto","to":"Basic_Machines","relationType":"defines_vision_for"}
|
||||
{"type":"relation","from":"Basic_Machines_Website","to":"Basic_Machines_Manifesto","relationType":"implements_vision_of"}
|
||||
{"type":"relation","from":"Basic_Factory","to":"AI_Human_Collaboration_Model","relationType":"demonstrates"}
|
||||
{"type":"relation","from":"Paul","to":"AI_Human_Collaboration_Model","relationType":"developed_with_Claude"}
|
||||
{"type":"relation","from":"Basic_Factory_Components","to":"Component_Translation_Process","relationType":"created_through"}
|
||||
{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic_Factory","relationType":"guides"}
|
||||
{"type":"relation","from":"Basic_Factory","to":"MCP_Tools","relationType":"integrates"}
|
||||
{"type":"relation","from":"Basic_Machines_Website","to":"Basic_Factory_Components","relationType":"will_use"}
|
||||
{"type":"relation","from":"Basic_Machines_Roadmap","to":"Basic_Machines_Philosophy","relationType":"aligns_with"}
|
||||
{"type":"relation","from":"Component_Translation_Process","to":"MCP_Tools","relationType":"leverages"}
|
||||
{"type":"relation","from":"Basic_Factory","to":"basic-memory","relationType":"will_document_process_in"}
|
||||
{"type":"relation","from":"AI_Human_Collaboration_Model","to":"basic-memory","relationType":"will_be_implemented_in"}
|
||||
{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic_Machines_Roadmap","relationType":"informs_priorities_of"}
|
||||
{"type":"relation","from":"basic-memory","to":"Basic_Machines_Philosophy","relationType":"embodies"}
|
||||
{"type":"relation","from":"Paul","to":"Basic_Machines_Manifesto","relationType":"authored_with_Claude"}
|
||||
{"type":"relation","from":"Basic_Factory","to":"Component_Translation_Process","relationType":"validated"}
|
||||
{"type":"relation","from":"AI_Human_Collaboration_Model","to":"MCP_Tools","relationType":"utilizes"}
|
||||
{"type":"relation","from":"Basic_Factory_Components","to":"Basic_Machines_Roadmap","relationType":"supports"}
|
||||
{"type":"relation","from":"Basic_Machines_Website","to":"Basic_Factory","relationType":"will_demonstrate"}
|
||||
{"type":"relation","from":"Basic_Factory","to":"basic-memory-webui","relationType":"enables_development_of"}
|
||||
{"type":"relation","from":"basic-memory","to":"AI_Human_Development_Methodology","relationType":"implements"}
|
||||
{"type":"relation","from":"Basic_Machines_Philosophy","to":"AI_Human_Development_Methodology","relationType":"guides"}
|
||||
{"type":"relation","from":"Basic_Factory_Components","to":"basic-memory-webui","relationType":"provides_ui_for"}
|
||||
{"type":"relation","from":"Component_Translation_Process","to":"AI_Human_Development_Methodology","relationType":"exemplifies"}
|
||||
{"type":"relation","from":"Basic_Factory","to":"Basic Components","relationType":"enabled_creation_of"}
|
||||
{"type":"relation","from":"Basic_Factory","to":"Tool Integration Discovery","relationType":"led_to"}
|
||||
{"type":"relation","from":"MCP_Integration_Progress","to":"AI_Human_Development_Methodology","relationType":"validates"}
|
||||
{"type":"relation","from":"Basic_Factory","to":"MCP_Integration_Progress","relationType":"demonstrates"}
|
||||
{"type":"relation","from":"Basic_Factory","to":"AI_Human_Development_Methodology","relationType":"proves_effectiveness_of"}
|
||||
{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic Components","relationType":"inspires_architecture_of"}
|
||||
{"type":"relation","from":"DIY_Ethics","to":"basic-memory","relationType":"shapes_design_of"}
|
||||
{"type":"relation","from":"Basic_Machines_Philosophy","to":"Tool Integration Discovery","relationType":"guides_analysis_of"}
|
||||
{"type":"relation","from":"Basic_Machines_Manifesto","to":"AI_Human_Development_Methodology","relationType":"documents_approach_of"}
|
||||
{"type":"relation","from":"Basic_Machines_Manifesto","to":"Basic_Factory_Components","relationType":"explains_principles_of"}
|
||||
{"type":"relation","from":"Basic_Memory_Project_Structure","to":"basic-memory","relationType":"organizes"}
|
||||
{"type":"relation","from":"Basic_Memory_Database_Schema","to":"basic-memory","relationType":"defines_storage_for"}
|
||||
{"type":"relation","from":"Basic_Memory_Markdown_Example","to":"Basic_Memory_File_Format","relationType":"demonstrates"}
|
||||
{"type":"relation","from":"Basic_Memory_Project_Isolation_Decision","to":"Basic_Memory_Future_Enhancement_Weighted_Relations","relationType":"similar_to"}
|
||||
{"type":"relation","to":"DIY_Ethics","from":"Basic_Memory_Project_Isolation_Decision","relationType":"follows"}
|
||||
{"type":"relation","from":"Basic_Memory_Implementation_Plan","to":"basic-memory","relationType":"guides"}
|
||||
{"type":"relation","from":"Basic_Memory_Implementation_Plan","to":"DIY_Ethics","relationType":"follows"}
|
||||
{"type":"relation","from":"Basic_Memory_Implementation_Plan","to":"Basic_Memory_Database_Schema","relationType":"implements"}
|
||||
{"type":"relation","from":"Basic_Memory_Implementation_Status","to":"Basic_Memory_Implementation_Plan","relationType":"updates"}
|
||||
{"type":"relation","from":"Basic_Memory_Observation_Management_Design","to":"Basic_Memory_Technical_Design","relationType":"extends"}
|
||||
{"type":"relation","from":"Basic_Memory_Architectural_Decisions","to":"DIY_Ethics","relationType":"guided_by"}
|
||||
{"type":"relation","from":"Basic_Memory_Architectural_Decisions","to":"basic-memory","relationType":"structures"}
|
||||
{"type":"relation","from":"Basic_Memory_Implementation_Status","to":"basic-memory","relationType":"describes_state_of"}
|
||||
{"type":"relation","to":"Basic_Memory_Implementation_Status","from":"Basic_Memory_Implementation_Analysis","relationType":"analyzes"}
|
||||
{"type":"relation","to":"basic-memory","from":"Basic_Memory_Current_Challenges","relationType":"identifies_issues_in"}
|
||||
{"type":"relation","to":"DIY_Ethics","from":"Basic_Memory_Implementation_Analysis","relationType":"confirms_alignment_with"}
|
||||
{"type":"relation","to":"Basic_Memory_Observation_Management_Design","from":"Basic_Memory_Observation_Hash_Tracking","relationType":"solves"}
|
||||
{"type":"relation","to":"DIY_Ethics","from":"Basic_Memory_Observation_Hash_Tracking","relationType":"aligns_with"}
|
||||
{"type":"relation","to":"Basic_Memory_File_Format","from":"Basic_Memory_Observation_Hash_Tracking","relationType":"preserves"}
|
||||
{"type":"relation","to":"Basic_Memory_Technical_Design","from":"Basic_Memory_Observation_Hash_Tracking","relationType":"enhances"}
|
||||
{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"basic-memory","relationType":"implements_part_of"}
|
||||
{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"Basic_Memory_Database_Schema","relationType":"follows"}
|
||||
{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"DIY_Ethics","relationType":"aligns_with"}
|
||||
{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"testing_infrastructure","relationType":"demonstrates"}
|
||||
{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"Basic Foundation","relationType":"inspired_by"}
|
||||
{"type":"relation","from":"Basic_Memory_Dependencies","to":"basic-memory","relationType":"supports"}
|
||||
{"type":"relation","from":"Basic_Memory_Dependencies","to":"Basic_Memory_Repository_Implementation","relationType":"enables"}
|
||||
{"type":"relation","from":"Basic_Memory_Dependencies","to":"testing_infrastructure","relationType":"enables"}
|
||||
{"type":"relation","from":"Basic_Memory_Current_Architecture","to":"basic-memory","relationType":"describes_state_of"}
|
||||
{"type":"relation","from":"Basic_Memory_Evolution","to":"Basic_Memory_Current_Architecture","relationType":"explains_development_of"}
|
||||
{"type":"relation","from":"Basic_Memory_Service_Layer","to":"Basic_Memory_Current_Architecture","relationType":"implements"}
|
||||
{"type":"relation","from":"Basic_Memory_Schema_Design","to":"Basic_Memory_Current_Architecture","relationType":"implements"}
|
||||
{"type":"relation","from":"Basic_Memory_Evolution","to":"Basic_Memory_Implementation_Plan","relationType":"reflects_on"}
|
||||
{"type":"relation","from":"Basic_Memory_Evolution","to":"DIY_Ethics","relationType":"demonstrates_alignment_with"}
|
||||
{"type":"relation","from":"Basic_Memory_Current_Architecture","to":"DIY_Ethics","relationType":"embodies"}
|
||||
{"type":"relation","from":"Basic_Memory_Service_Layer","to":"fileio_module","relationType":"uses"}
|
||||
{"type":"relation","from":"Basic_Memory_Schema_Design","to":"markdown_format","relationType":"implements"}
|
||||
{"type":"relation","to":"basic-memory","from":"Basic_Memory_Next_Tasks","relationType":"guides_development_of"}
|
||||
{"type":"relation","to":"DIY_Ethics","from":"Basic_Memory_Next_Tasks","relationType":"aligns_with"}
|
||||
{"type":"relation","to":"Basic_Memory_Current_Architecture","from":"Basic_Memory_Next_Tasks","relationType":"extends"}
|
||||
{"type":"relation","from":"Basic_Memory_Meta_Experience","to":"basic-memory","relationType":"validates_design_of"}
|
||||
{"type":"relation","from":"Basic_Memory_Meta_Experience","to":"DIY_Ethics","relationType":"demonstrates_principles_of"}
|
||||
{"type":"relation","from":"Basic_Memory_Meta_Experience","to":"design_decisions","relationType":"reinforces"}
|
||||
{"type":"relation","from":"Basic_Memory_Meta_Experience","to":"Basic_Memory_Current_Architecture","relationType":"validates"}
|
||||
@@ -0,0 +1,68 @@
|
||||
# Basic Memory Tasks
|
||||
|
||||
## 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.
|
||||
|
||||
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
|
||||
|
||||
2. Tracked Observations Approach
|
||||
- Use markdown comments for observation IDs
|
||||
```markdown
|
||||
# Entity Name
|
||||
type: entity_type
|
||||
|
||||
## Observations
|
||||
- <!-- 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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user