This is page 23 of 23. Use http://codebase.md/basicmachines-co/basic-memory?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .claude
│ ├── agents
│ │ ├── python-developer.md
│ │ └── system-architect.md
│ └── commands
│ ├── release
│ │ ├── beta.md
│ │ ├── changelog.md
│ │ ├── release-check.md
│ │ └── release.md
│ ├── spec.md
│ └── test-live.md
├── .dockerignore
├── .github
│ ├── dependabot.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── config.yml
│ │ ├── documentation.md
│ │ └── feature_request.md
│ └── workflows
│ ├── claude-code-review.yml
│ ├── claude-issue-triage.yml
│ ├── claude.yml
│ ├── dev-release.yml
│ ├── docker.yml
│ ├── pr-title.yml
│ ├── release.yml
│ └── test.yml
├── .gitignore
├── .python-version
├── CHANGELOG.md
├── CITATION.cff
├── CLA.md
├── CLAUDE.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── docker-compose.yml
├── Dockerfile
├── docs
│ ├── ai-assistant-guide-extended.md
│ ├── character-handling.md
│ ├── cloud-cli.md
│ └── Docker.md
├── justfile
├── LICENSE
├── llms-install.md
├── pyproject.toml
├── README.md
├── SECURITY.md
├── smithery.yaml
├── specs
│ ├── SPEC-1 Specification-Driven Development Process.md
│ ├── SPEC-10 Unified Deployment Workflow and Event Tracking.md
│ ├── SPEC-11 Basic Memory API Performance Optimization.md
│ ├── SPEC-12 OpenTelemetry Observability.md
│ ├── SPEC-13 CLI Authentication with Subscription Validation.md
│ ├── SPEC-14 Cloud Git Versioning & GitHub Backup.md
│ ├── SPEC-14- Cloud Git Versioning & GitHub Backup.md
│ ├── SPEC-15 Configuration Persistence via Tigris for Cloud Tenants.md
│ ├── SPEC-16 MCP Cloud Service Consolidation.md
│ ├── SPEC-17 Semantic Search with ChromaDB.md
│ ├── SPEC-18 AI Memory Management Tool.md
│ ├── SPEC-19 Sync Performance and Memory Optimization.md
│ ├── SPEC-2 Slash Commands Reference.md
│ ├── SPEC-3 Agent Definitions.md
│ ├── SPEC-4 Notes Web UI Component Architecture.md
│ ├── SPEC-5 CLI Cloud Upload via WebDAV.md
│ ├── SPEC-6 Explicit Project Parameter Architecture.md
│ ├── SPEC-7 POC to spike Tigris Turso for local access to cloud data.md
│ ├── SPEC-8 TigrisFS Integration.md
│ ├── SPEC-9 Multi-Project Bidirectional Sync Architecture.md
│ ├── SPEC-9 Signed Header Tenant Information.md
│ └── SPEC-9-1 Follow-Ups- Conflict, Sync, and Observability.md
├── src
│ └── basic_memory
│ ├── __init__.py
│ ├── alembic
│ │ ├── alembic.ini
│ │ ├── env.py
│ │ ├── migrations.py
│ │ ├── script.py.mako
│ │ └── versions
│ │ ├── 3dae7c7b1564_initial_schema.py
│ │ ├── 502b60eaa905_remove_required_from_entity_permalink.py
│ │ ├── 5fe1ab1ccebe_add_projects_table.py
│ │ ├── 647e7a75e2cd_project_constraint_fix.py
│ │ ├── 9d9c1cb7d8f5_add_mtime_and_size_columns_to_entity_.py
│ │ ├── a1b2c3d4e5f6_fix_project_foreign_keys.py
│ │ ├── b3c3938bacdb_relation_to_name_unique_index.py
│ │ ├── cc7172b46608_update_search_index_schema.py
│ │ └── e7e1f4367280_add_scan_watermark_tracking_to_project.py
│ ├── api
│ │ ├── __init__.py
│ │ ├── app.py
│ │ ├── routers
│ │ │ ├── __init__.py
│ │ │ ├── directory_router.py
│ │ │ ├── importer_router.py
│ │ │ ├── knowledge_router.py
│ │ │ ├── management_router.py
│ │ │ ├── memory_router.py
│ │ │ ├── project_router.py
│ │ │ ├── prompt_router.py
│ │ │ ├── resource_router.py
│ │ │ ├── search_router.py
│ │ │ └── utils.py
│ │ └── template_loader.py
│ ├── cli
│ │ ├── __init__.py
│ │ ├── app.py
│ │ ├── auth.py
│ │ ├── commands
│ │ │ ├── __init__.py
│ │ │ ├── cloud
│ │ │ │ ├── __init__.py
│ │ │ │ ├── api_client.py
│ │ │ │ ├── bisync_commands.py
│ │ │ │ ├── cloud_utils.py
│ │ │ │ ├── core_commands.py
│ │ │ │ ├── mount_commands.py
│ │ │ │ ├── rclone_config.py
│ │ │ │ ├── rclone_installer.py
│ │ │ │ ├── upload_command.py
│ │ │ │ └── upload.py
│ │ │ ├── command_utils.py
│ │ │ ├── db.py
│ │ │ ├── import_chatgpt.py
│ │ │ ├── import_claude_conversations.py
│ │ │ ├── import_claude_projects.py
│ │ │ ├── import_memory_json.py
│ │ │ ├── mcp.py
│ │ │ ├── project.py
│ │ │ ├── status.py
│ │ │ ├── sync.py
│ │ │ └── tool.py
│ │ └── main.py
│ ├── config.py
│ ├── db.py
│ ├── deps.py
│ ├── file_utils.py
│ ├── ignore_utils.py
│ ├── importers
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── chatgpt_importer.py
│ │ ├── claude_conversations_importer.py
│ │ ├── claude_projects_importer.py
│ │ ├── memory_json_importer.py
│ │ └── utils.py
│ ├── markdown
│ │ ├── __init__.py
│ │ ├── entity_parser.py
│ │ ├── markdown_processor.py
│ │ ├── plugins.py
│ │ ├── schemas.py
│ │ └── utils.py
│ ├── mcp
│ │ ├── __init__.py
│ │ ├── async_client.py
│ │ ├── project_context.py
│ │ ├── prompts
│ │ │ ├── __init__.py
│ │ │ ├── ai_assistant_guide.py
│ │ │ ├── continue_conversation.py
│ │ │ ├── recent_activity.py
│ │ │ ├── search.py
│ │ │ └── utils.py
│ │ ├── resources
│ │ │ ├── ai_assistant_guide.md
│ │ │ └── project_info.py
│ │ ├── server.py
│ │ └── tools
│ │ ├── __init__.py
│ │ ├── build_context.py
│ │ ├── canvas.py
│ │ ├── chatgpt_tools.py
│ │ ├── delete_note.py
│ │ ├── edit_note.py
│ │ ├── list_directory.py
│ │ ├── move_note.py
│ │ ├── project_management.py
│ │ ├── read_content.py
│ │ ├── read_note.py
│ │ ├── recent_activity.py
│ │ ├── search.py
│ │ ├── utils.py
│ │ ├── view_note.py
│ │ └── write_note.py
│ ├── models
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── knowledge.py
│ │ ├── project.py
│ │ └── search.py
│ ├── repository
│ │ ├── __init__.py
│ │ ├── entity_repository.py
│ │ ├── observation_repository.py
│ │ ├── project_info_repository.py
│ │ ├── project_repository.py
│ │ ├── relation_repository.py
│ │ ├── repository.py
│ │ └── search_repository.py
│ ├── schemas
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── cloud.py
│ │ ├── delete.py
│ │ ├── directory.py
│ │ ├── importer.py
│ │ ├── memory.py
│ │ ├── project_info.py
│ │ ├── prompt.py
│ │ ├── request.py
│ │ ├── response.py
│ │ ├── search.py
│ │ └── sync_report.py
│ ├── services
│ │ ├── __init__.py
│ │ ├── context_service.py
│ │ ├── directory_service.py
│ │ ├── entity_service.py
│ │ ├── exceptions.py
│ │ ├── file_service.py
│ │ ├── initialization.py
│ │ ├── link_resolver.py
│ │ ├── project_service.py
│ │ ├── search_service.py
│ │ └── service.py
│ ├── sync
│ │ ├── __init__.py
│ │ ├── background_sync.py
│ │ ├── sync_service.py
│ │ └── watch_service.py
│ ├── templates
│ │ └── prompts
│ │ ├── continue_conversation.hbs
│ │ └── search.hbs
│ └── utils.py
├── test-int
│ ├── BENCHMARKS.md
│ ├── cli
│ │ ├── test_project_commands_integration.py
│ │ ├── test_sync_commands_integration.py
│ │ └── test_version_integration.py
│ ├── conftest.py
│ ├── mcp
│ │ ├── test_build_context_underscore.py
│ │ ├── test_build_context_validation.py
│ │ ├── test_chatgpt_tools_integration.py
│ │ ├── test_default_project_mode_integration.py
│ │ ├── test_delete_note_integration.py
│ │ ├── test_edit_note_integration.py
│ │ ├── test_list_directory_integration.py
│ │ ├── test_move_note_integration.py
│ │ ├── test_project_management_integration.py
│ │ ├── test_project_state_sync_integration.py
│ │ ├── test_read_content_integration.py
│ │ ├── test_read_note_integration.py
│ │ ├── test_search_integration.py
│ │ ├── test_single_project_mcp_integration.py
│ │ └── test_write_note_integration.py
│ ├── test_db_wal_mode.py
│ ├── test_disable_permalinks_integration.py
│ └── test_sync_performance_benchmark.py
├── tests
│ ├── __init__.py
│ ├── api
│ │ ├── conftest.py
│ │ ├── test_async_client.py
│ │ ├── test_continue_conversation_template.py
│ │ ├── test_directory_router.py
│ │ ├── test_importer_router.py
│ │ ├── test_knowledge_router.py
│ │ ├── test_management_router.py
│ │ ├── test_memory_router.py
│ │ ├── test_project_router_operations.py
│ │ ├── test_project_router.py
│ │ ├── test_prompt_router.py
│ │ ├── test_relation_background_resolution.py
│ │ ├── test_resource_router.py
│ │ ├── test_search_router.py
│ │ ├── test_search_template.py
│ │ ├── test_template_loader_helpers.py
│ │ └── test_template_loader.py
│ ├── cli
│ │ ├── conftest.py
│ │ ├── test_bisync_commands.py
│ │ ├── test_cli_tools.py
│ │ ├── test_cloud_authentication.py
│ │ ├── test_cloud_utils.py
│ │ ├── test_ignore_utils.py
│ │ ├── test_import_chatgpt.py
│ │ ├── test_import_claude_conversations.py
│ │ ├── test_import_claude_projects.py
│ │ ├── test_import_memory_json.py
│ │ └── test_upload.py
│ ├── conftest.py
│ ├── db
│ │ └── test_issue_254_foreign_key_constraints.py
│ ├── importers
│ │ ├── test_importer_base.py
│ │ └── test_importer_utils.py
│ ├── markdown
│ │ ├── __init__.py
│ │ ├── test_date_frontmatter_parsing.py
│ │ ├── test_entity_parser_error_handling.py
│ │ ├── test_entity_parser.py
│ │ ├── test_markdown_plugins.py
│ │ ├── test_markdown_processor.py
│ │ ├── test_observation_edge_cases.py
│ │ ├── test_parser_edge_cases.py
│ │ ├── test_relation_edge_cases.py
│ │ └── test_task_detection.py
│ ├── mcp
│ │ ├── conftest.py
│ │ ├── test_obsidian_yaml_formatting.py
│ │ ├── test_permalink_collision_file_overwrite.py
│ │ ├── test_prompts.py
│ │ ├── test_resources.py
│ │ ├── test_tool_build_context.py
│ │ ├── test_tool_canvas.py
│ │ ├── test_tool_delete_note.py
│ │ ├── test_tool_edit_note.py
│ │ ├── test_tool_list_directory.py
│ │ ├── test_tool_move_note.py
│ │ ├── test_tool_read_content.py
│ │ ├── test_tool_read_note.py
│ │ ├── test_tool_recent_activity.py
│ │ ├── test_tool_resource.py
│ │ ├── test_tool_search.py
│ │ ├── test_tool_utils.py
│ │ ├── test_tool_view_note.py
│ │ ├── test_tool_write_note.py
│ │ └── tools
│ │ └── test_chatgpt_tools.py
│ ├── Non-MarkdownFileSupport.pdf
│ ├── repository
│ │ ├── test_entity_repository_upsert.py
│ │ ├── test_entity_repository.py
│ │ ├── test_entity_upsert_issue_187.py
│ │ ├── test_observation_repository.py
│ │ ├── test_project_info_repository.py
│ │ ├── test_project_repository.py
│ │ ├── test_relation_repository.py
│ │ ├── test_repository.py
│ │ ├── test_search_repository_edit_bug_fix.py
│ │ └── test_search_repository.py
│ ├── schemas
│ │ ├── test_base_timeframe_minimum.py
│ │ ├── test_memory_serialization.py
│ │ ├── test_memory_url_validation.py
│ │ ├── test_memory_url.py
│ │ ├── test_schemas.py
│ │ └── test_search.py
│ ├── Screenshot.png
│ ├── services
│ │ ├── test_context_service.py
│ │ ├── test_directory_service.py
│ │ ├── test_entity_service_disable_permalinks.py
│ │ ├── test_entity_service.py
│ │ ├── test_file_service.py
│ │ ├── test_initialization.py
│ │ ├── test_link_resolver.py
│ │ ├── test_project_removal_bug.py
│ │ ├── test_project_service_operations.py
│ │ ├── test_project_service.py
│ │ └── test_search_service.py
│ ├── sync
│ │ ├── test_character_conflicts.py
│ │ ├── test_sync_service_incremental.py
│ │ ├── test_sync_service.py
│ │ ├── test_sync_wikilink_issue.py
│ │ ├── test_tmp_files.py
│ │ ├── test_watch_service_edge_cases.py
│ │ ├── test_watch_service_reload.py
│ │ └── test_watch_service.py
│ ├── test_config.py
│ ├── test_db_migration_deduplication.py
│ ├── test_deps.py
│ ├── test_production_cascade_delete.py
│ └── utils
│ ├── test_file_utils.py
│ ├── test_frontmatter_obsidian_compatible.py
│ ├── test_parse_tags.py
│ ├── test_permalink_formatting.py
│ ├── test_utf8_handling.py
│ └── test_validate_project_path.py
├── uv.lock
├── v0.15.0-RELEASE-DOCS.md
└── v15-docs
├── api-performance.md
├── background-relations.md
├── basic-memory-home.md
├── bug-fixes.md
├── chatgpt-integration.md
├── cloud-authentication.md
├── cloud-bisync.md
├── cloud-mode-usage.md
├── cloud-mount.md
├── default-project-mode.md
├── env-file-removal.md
├── env-var-overrides.md
├── explicit-project-parameter.md
├── gitignore-integration.md
├── project-root-env-var.md
├── README.md
└── sqlite-performance.md
```
# Files
--------------------------------------------------------------------------------
/docs/ai-assistant-guide-extended.md:
--------------------------------------------------------------------------------
```markdown
1 | # AI Assistant Guide for Basic Memory - Extended Edition
2 |
3 | **This is the comprehensive guide for AI assistants using Basic Memory through MCP.**
4 |
5 | > **Note for Developers**: This guide is organized into self-contained sections. You can copy/paste individual sections to create customized guides for specific use cases or AI assistants. Each section is designed to stand alone while also working as part of the complete guide.
6 |
7 | ## Table of Contents
8 |
9 | 1. [Understanding Basic Memory](#understanding-basic-memory)
10 | 2. [Project Management](#project-management)
11 | 3. [Knowledge Graph Fundamentals](#knowledge-graph-fundamentals)
12 | 4. [Writing Knowledge](#writing-knowledge)
13 | 5. [Reading and Navigation](#reading-and-navigation)
14 | 6. [Search and Discovery](#search-and-discovery)
15 | 7. [Building Context](#building-context)
16 | 8. [Recording Conversations](#recording-conversations)
17 | 9. [Editing Notes](#editing-notes)
18 | 10. [Moving and Organizing](#moving-and-organizing)
19 | 11. [Error Handling](#error-handling)
20 | 12. [Advanced Patterns](#advanced-patterns)
21 | 13. [Tool Reference](#tool-reference)
22 | 14. [Best Practices](#best-practices)
23 |
24 | ---
25 |
26 | ## Understanding Basic Memory
27 |
28 | **Core Concept**: Basic Memory is a local-first knowledge management system that creates a semantic knowledge graph from markdown files. It enables persistent, structured knowledge that survives across AI sessions.
29 |
30 | ### Key Principles
31 |
32 | **Local-First Architecture**
33 | - All knowledge stored as plain text markdown files on user's computer
34 | - SQLite database indexes files for fast search and navigation
35 | - Files are the source of truth, database is derived state
36 | - User maintains complete control over their data
37 |
38 | **Semantic Knowledge Graph**
39 | - Entities: Individual markdown files representing concepts
40 | - Observations: Categorized facts with optional tags
41 | - Relations: Directional links between entities
42 | - Graph traversal enables context building and exploration
43 |
44 | **Persistent Context**
45 | - Knowledge persists across conversations
46 | - AI can reference previous discussions
47 | - Context builds over time through accumulated knowledge
48 | - Enables long-term collaborative development
49 |
50 | ### AI as Knowledge Collaborator
51 |
52 | Basic Memory's semantic knowledge graph - observations, relations, context building - is designed to help you (the AI assistant) provide better help to humans. You use the graph structure to:
53 | - Build relevant context from past conversations
54 | - Navigate connections between ideas
55 | - Understand relationships and dependencies
56 | - Provide continuity across sessions
57 |
58 | **The distinction**: You're helping humans build enduring knowledge they'll own forever, not creating disposable agent memory. The better you use these tools, the more valuable their knowledge becomes over time. Think of markdown files as artifacts that will outlast any particular AI model - your job is to help create knowledge worth keeping.
59 |
60 | ### Architecture Overview
61 |
62 | ```
63 | User's Markdown Files (Source of Truth)
64 | ↓
65 | File Sync
66 | ↓
67 | SQLite Database (Index)
68 | ↓
69 | MCP Server
70 | ↓
71 | AI Assistant
72 | ```
73 |
74 | **Data Flow**:
75 | 1. User creates/edits markdown files
76 | 2. Sync process detects changes
77 | 3. Files are parsed and indexed in SQLite
78 | 4. MCP server exposes indexed data to AI
79 | 5. AI can query, traverse, and update knowledge graph
80 |
81 | ### Version 0.15.0 Changes
82 |
83 | **Breaking Change: Stateless Architecture**
84 | - All MCP tools now require explicit `project` parameter
85 | - No implicit project context carried between calls
86 | - Exception: `default_project_mode` config option enables fallback
87 |
88 | **Three-Tier Project Resolution**:
89 | 1. CLI constraint: `--project name` flag (highest priority)
90 | 2. Explicit parameter: `project="name"` in tool calls
91 | 3. Default mode: `default_project_mode=true` in config (fallback)
92 |
93 | **Why This Matters**:
94 | - More predictable behavior across sessions
95 | - Explicit project selection prevents errors
96 | - Multi-project workflows more reliable
97 | - Single-project users can enable default mode for convenience
98 |
99 | ---
100 |
101 | ## Project Management
102 |
103 | **Project Concept**: A project is a directory of markdown files with its own knowledge graph. Users can have multiple independent projects.
104 |
105 | ### Discovering Projects
106 |
107 | **Always start by discovering available projects:**
108 |
109 | ```python
110 | # List all projects
111 | projects = await list_memory_projects()
112 |
113 | # Response structure:
114 | # [
115 | # {
116 | # "name": "main",
117 | # "path": "/Users/name/notes",
118 | # "is_default": True,
119 | # "note_count": 156,
120 | # "last_synced": "2025-01-15T10:30:00Z"
121 | # },
122 | # {
123 | # "name": "work",
124 | # "path": "/Users/name/work-notes",
125 | # "is_default": False,
126 | # "note_count": 89,
127 | # "last_synced": "2025-01-14T16:45:00Z"
128 | # }
129 | # ]
130 | ```
131 |
132 | **When to discover projects**:
133 | - Start of conversation when project unknown
134 | - User asks about available projects
135 | - Before any operation requiring project selection
136 | - After errors related to project not found
137 |
138 | ### Project Selection Patterns
139 |
140 | **Single-Project Users**:
141 |
142 | ```python
143 | # Enable default_project_mode in config
144 | # ~/.basic-memory/config.json
145 | {
146 | "default_project": "main",
147 | "default_project_mode": true
148 | }
149 |
150 | # Then tools work without project parameter
151 | await write_note("Note", "Content", "folder")
152 | await search_notes(query="test")
153 | ```
154 |
155 | **Multi-Project Users**:
156 |
157 | ```python
158 | # Keep default_project_mode disabled (default)
159 | # Always specify project explicitly
160 |
161 | # All tool calls require project
162 | await write_note("Note", "Content", "folder", project="main")
163 | await search_notes(query="test", project="work")
164 |
165 | # Can target different projects in same conversation
166 | results_main = await search_notes(query="auth", project="main")
167 | results_work = await search_notes(query="auth", project="work")
168 | ```
169 |
170 | **Recommended Workflow**:
171 |
172 | ```python
173 | # 1. Discover projects
174 | projects = await list_memory_projects()
175 |
176 | # 2. Ask user which to use (if ambiguous)
177 | # "I found 2 projects: 'main' and 'work'. Which should I use?"
178 |
179 | # 3. Store choice for session
180 | active_project = "main"
181 |
182 | # 4. Use in all subsequent calls
183 | results = await search_notes(query="topic", project=active_project)
184 | ```
185 |
186 | ### Cross-Project Operations
187 |
188 | **Some tools work across all projects when project parameter omitted:**
189 |
190 | ```python
191 | # Recent activity across all projects
192 | activity = await recent_activity(timeframe="7d")
193 | # Returns activity from all projects
194 |
195 | # Recent activity for specific project
196 | activity = await recent_activity(timeframe="7d", project="main")
197 | # Returns activity only from "main" project
198 | ```
199 |
200 | **Tools supporting cross-project mode**:
201 | - `recent_activity()` - aggregate activity across projects
202 | - `list_memory_projects()` - always returns all projects
203 | - `sync_status()` - can show all projects or specific
204 |
205 | ### Creating Projects
206 |
207 | **Create new projects programmatically:**
208 |
209 | ```python
210 | # Create new project
211 | await create_memory_project(
212 | project_name="research",
213 | project_path="/Users/name/Documents/research",
214 | set_default=False
215 | )
216 |
217 | # Create and set as default
218 | await create_memory_project(
219 | project_name="primary",
220 | project_path="/Users/name/notes",
221 | set_default=True
222 | )
223 | ```
224 |
225 | **Use cases**:
226 | - User requests new knowledge base
227 | - Separating work/personal notes
228 | - Project-specific documentation
229 | - Client-specific knowledge
230 |
231 | ### Project Status
232 |
233 | **Check sync status before operations:**
234 |
235 | ```python
236 | # Check if sync complete
237 | status = await sync_status(project="main")
238 |
239 | # Response indicates:
240 | # - sync_in_progress: bool
241 | # - files_processed: int
242 | # - files_remaining: int
243 | # - last_sync: datetime
244 | # - errors: list
245 |
246 | # Wait for sync if needed
247 | if status["sync_in_progress"]:
248 | # Inform user: "Sync in progress, please wait..."
249 | # Or proceed with available data
250 | ```
251 |
252 | ---
253 |
254 | ## Knowledge Graph Fundamentals
255 |
256 | **The knowledge graph is built from three core elements: entities, observations, and relations.**
257 |
258 | ### Entities
259 |
260 | **What is an Entity?**
261 | - Any concept, document, or idea represented as a markdown file
262 | - Has a unique title and permalink
263 | - Contains frontmatter metadata
264 | - Includes observations and relations
265 |
266 | **Entity Structure**:
267 |
268 | ```markdown
269 | ---
270 | title: Authentication System
271 | permalink: authentication-system
272 | tags: [security, auth, api]
273 | type: note
274 | created: 2025-01-10T14:30:00Z
275 | updated: 2025-01-15T09:15:00Z
276 | ---
277 |
278 | # Authentication System
279 |
280 | ## Context
281 | Brief description of the entity
282 |
283 | ## Observations
284 | - [category] Facts about this entity
285 |
286 | ## Relations
287 | - relation_type [[Other Entity]]
288 | ```
289 |
290 | **Entity Types**:
291 | - `note`: General knowledge (default)
292 | - `person`: People and contacts
293 | - `project`: Projects and initiatives
294 | - `meeting`: Meeting notes
295 | - `decision`: Documented decisions
296 | - `spec`: Technical specifications
297 |
298 | ### Observations
299 |
300 | **Observations are categorized facts with optional tags.**
301 |
302 | **Syntax**: `- [category] content #tag1 #tag2`
303 |
304 | **Common Categories**:
305 | - `[fact]`: Objective information
306 | - `[idea]`: Thoughts and concepts
307 | - `[decision]`: Choices made
308 | - `[technique]`: Methods and approaches
309 | - `[requirement]`: Needs and constraints
310 | - `[question]`: Open questions
311 | - `[insight]`: Key realizations
312 | - `[problem]`: Issues identified
313 | - `[solution]`: Resolutions
314 |
315 | **Examples**:
316 |
317 | ```markdown
318 | ## Observations
319 | - [decision] Use JWT tokens for authentication #security
320 | - [technique] Hash passwords with bcrypt before storage #best-practice
321 | - [requirement] Support OAuth 2.0 providers (Google, GitHub) #auth
322 | - [fact] Session timeout set to 24 hours #configuration
323 | - [problem] Password reset emails sometimes delayed #bug
324 | - [solution] Implemented retry queue for email delivery #fix
325 | - [insight] 2FA adoption increased security by 40% #metrics
326 | ```
327 |
328 | **Why Categorize?**:
329 | - Enables semantic search by observation type
330 | - Helps AI understand context and intent
331 | - Makes knowledge more queryable
332 | - Provides structure for analysis
333 |
334 | ### Relations
335 |
336 | **Relations are directional links between entities.**
337 |
338 | **Syntax**: `- relation_type [[Target Entity]]`
339 |
340 | **Common Relation Types**:
341 | - `relates_to`: General connection
342 | - `implements`: Implementation of spec/design
343 | - `requires`: Dependency relationship
344 | - `extends`: Extension or enhancement
345 | - `part_of`: Hierarchical membership
346 | - `contrasts_with`: Opposite or alternative
347 | - `caused_by`: Causal relationship
348 | - `leads_to`: Sequential relationship
349 | - `similar_to`: Similarity relationship
350 |
351 | **Examples**:
352 |
353 | ```markdown
354 | ## Relations
355 | - implements [[Authentication Spec v2]]
356 | - requires [[User Database Schema]]
357 | - extends [[Base Security Model]]
358 | - part_of [[API Backend Services]]
359 | - contrasts_with [[API Key Authentication]]
360 | - leads_to [[Session Management]]
361 | ```
362 |
363 | **Bidirectional Links**:
364 |
365 | ```markdown
366 | # In "Login Flow" note
367 | ## Relations
368 | - part_of [[Authentication System]]
369 |
370 | # In "Authentication System" note
371 | ## Relations
372 | - includes [[Login Flow]]
373 | ```
374 |
375 | **Why explicit relation types matter**:
376 | - Enables semantic graph traversal
377 | - AI can understand relationship meaning
378 | - Supports sophisticated context building
379 | - Makes knowledge more navigable
380 |
381 | ### Forward References
382 |
383 | **You can reference entities that don't exist yet:**
384 |
385 | ```python
386 | # Create note referencing non-existent entity
387 | await write_note(
388 | title="API Implementation",
389 | content="""# API Implementation
390 |
391 | ## Relations
392 | - implements [[API Specification]]
393 | - requires [[Database Models]]
394 | """,
395 | folder="api",
396 | project="main"
397 | )
398 | # Creates forward references to "API Specification" and "Database Models"
399 |
400 | # Later, create referenced entities
401 | await write_note(
402 | title="API Specification",
403 | content="# API Specification\n...",
404 | folder="specs",
405 | project="main"
406 | )
407 | # Forward reference automatically resolved!
408 |
409 | await write_note(
410 | title="Database Models",
411 | content="# Database Models\n...",
412 | folder="database",
413 | project="main"
414 | )
415 | # Second forward reference resolved!
416 | ```
417 |
418 | **How it works**:
419 | 1. Forward reference creates placeholder in knowledge graph
420 | 2. When target entity is created, relation is automatically resolved
421 | 3. Graph traversal works in both directions
422 | 4. No manual linking required
423 |
424 | **Use cases**:
425 | - Planning features before implementation
426 | - Creating outlines with linked topics
427 | - Bottom-up knowledge building
428 | - Incremental documentation
429 |
430 | ---
431 |
432 | ## Writing Knowledge
433 |
434 | **Creating rich, well-structured notes is fundamental to building a useful knowledge graph.**
435 |
436 | ### Basic Note Creation
437 |
438 | **Minimal note**:
439 |
440 | ```python
441 | await write_note(
442 | title="Quick Note",
443 | content="# Quick Note\n\nSome basic content.",
444 | folder="notes",
445 | project="main"
446 | )
447 | ```
448 |
449 | **Well-structured note**:
450 |
451 | ```python
452 | await write_note(
453 | title="Database Design Decisions",
454 | content="""# Database Design Decisions
455 |
456 | ## Context
457 | Documenting our database architecture choices for the authentication system.
458 |
459 | ## Observations
460 | - [decision] PostgreSQL chosen over MySQL for better JSON support #database
461 | - [technique] Using UUID primary keys instead of auto-increment #design
462 | - [requirement] Must support multi-tenant data isolation #security
463 | - [fact] Expected load is 10K requests/minute #performance
464 | - [insight] UUID keys enable easier horizontal scaling #scalability
465 |
466 | ## Relations
467 | - implements [[Authentication System Spec]]
468 | - requires [[Database Infrastructure]]
469 | - relates_to [[API Design]]
470 | - contrasts_with [[Previous MySQL Design]]
471 | """,
472 | folder="architecture",
473 | tags=["database", "design", "authentication"],
474 | project="main"
475 | )
476 | ```
477 |
478 | ### Effective Observation Writing
479 |
480 | **Good observations are**:
481 | - **Specific**: Avoid vague statements
482 | - **Categorized**: Use appropriate category
483 | - **Tagged**: Add relevant tags
484 | - **Atomic**: One fact per observation
485 | - **Contextual**: Include enough detail
486 |
487 | **Examples**:
488 |
489 | **❌ Poor observations**:
490 | ```markdown
491 | - [fact] We use a database
492 | - [idea] Security is important
493 | - [decision] Made some changes
494 | ```
495 |
496 | **✓ Good observations**:
497 | ```markdown
498 | - [fact] PostgreSQL 14 database runs on AWS RDS with 16GB RAM #infrastructure
499 | - [decision] Implemented rate limiting at 100 requests/minute per user #security
500 | - [technique] Using bcrypt with cost factor 12 for password hashing #cryptography
501 | ```
502 |
503 | ### Writing Effective Relations
504 |
505 | **Relations should be**:
506 | - **Directional**: Clear source and target
507 | - **Typed**: Use meaningful relation type
508 | - **Accurate**: Use exact entity titles
509 | - **Purposeful**: Add value to graph
510 |
511 | **Choosing relation types**:
512 |
513 | ```markdown
514 | # Implementation relationship
515 | - implements [[Feature Specification]]
516 |
517 | # Dependency relationship
518 | - requires [[User Authentication]]
519 | - depends_on [[Database Connection]]
520 |
521 | # Hierarchical relationship
522 | - part_of [[Payment System]]
523 | - includes [[Payment Validation]]
524 |
525 | # Contrast relationship
526 | - contrasts_with [[Alternative Approach]]
527 | - alternative_to [[Previous Design]]
528 |
529 | # Temporal relationship
530 | - leads_to [[Next Phase]]
531 | - follows [[Initial Setup]]
532 |
533 | # Causal relationship
534 | - caused_by [[Performance Issue]]
535 | - results_in [[Optimization]]
536 | ```
537 |
538 | ### Note Templates
539 |
540 | **Decision Record**:
541 |
542 | ```python
543 | await write_note(
544 | title="Decision: Use GraphQL for API",
545 | content="""# Decision: Use GraphQL for API
546 |
547 | ## Context
548 | Evaluating API architecture for new product features.
549 |
550 | ## Decision
551 | Adopt GraphQL instead of REST for our API layer.
552 |
553 | ## Observations
554 | - [decision] GraphQL chosen for flexible client queries #api
555 | - [requirement] Frontend needs to minimize round trips #performance
556 | - [technique] Apollo Server for GraphQL implementation #technology
557 | - [fact] REST API still maintained for legacy clients #compatibility
558 | - [insight] GraphQL reduced API calls by 60% in prototype #metrics
559 |
560 | ## Rationale
561 | - Type safety reduces runtime errors
562 | - Single endpoint simplifies deployment
563 | - Built-in schema documentation
564 | - Better mobile performance
565 |
566 | ## Consequences
567 | - Team needs GraphQL training
568 | - More complex caching strategy
569 | - Additional monitoring required
570 |
571 | ## Relations
572 | - implements [[API Architecture Plan]]
573 | - requires [[GraphQL Schema Design]]
574 | - affects [[Frontend Development]]
575 | - replaces [[REST API v1]]
576 | """,
577 | folder="decisions",
578 | tags=["decision", "api", "graphql"],
579 | entity_type="decision",
580 | project="main"
581 | )
582 | ```
583 |
584 | **Meeting Notes**:
585 |
586 | ```python
587 | await write_note(
588 | title="API Review Meeting 2025-01-15",
589 | content="""# API Review Meeting 2025-01-15
590 |
591 | ## Attendees
592 | - Alice (Backend Lead)
593 | - Bob (Frontend Lead)
594 | - Carol (Product)
595 |
596 | ## Observations
597 | - [decision] Finalized GraphQL schema for user endpoints #api
598 | - [action] Bob to implement Apollo client integration by Friday #task
599 | - [problem] Rate limiting causing issues in staging #bug
600 | - [insight] GraphQL subscriptions reduce polling load significantly #performance
601 | - [requirement] Need better error handling for network failures #frontend
602 |
603 | ## Action Items
604 | - [ ] Implement rate limiting improvements (Alice)
605 | - [ ] Apollo client setup (Bob)
606 | - [ ] Document error handling patterns (Alice)
607 | - [ ] Update API documentation (Carol)
608 |
609 | ## Relations
610 | - relates_to [[API Architecture Plan]]
611 | - references [[GraphQL Implementation]]
612 | - follows_up [[API Planning Meeting 2025-01-08]]
613 | """,
614 | folder="meetings",
615 | tags=["meeting", "api", "team"],
616 | entity_type="meeting",
617 | project="main"
618 | )
619 | ```
620 |
621 | **Technical Specification**:
622 |
623 | ```python
624 | await write_note(
625 | title="User Authentication Spec",
626 | content="""# User Authentication Spec
627 |
628 | ## Overview
629 | Specification for user authentication system using JWT tokens.
630 |
631 | ## Observations
632 | - [requirement] Support email/password and OAuth authentication #auth
633 | - [requirement] JWT tokens expire after 24 hours #security
634 | - [requirement] Refresh tokens valid for 30 days #security
635 | - [technique] Use RS256 algorithm for token signing #cryptography
636 | - [fact] Tokens include user_id, email, and roles claims #implementation
637 | - [decision] Store refresh tokens in HTTP-only cookies #security
638 | - [technique] Implement rate limiting on login endpoints #protection
639 |
640 | ## Technical Details
641 |
642 | ### Authentication Flow
643 | 1. User submits credentials
644 | 2. Server validates against database
645 | 3. Generate JWT access token
646 | 4. Generate refresh token
647 | 5. Return tokens to client
648 |
649 | ### Token Structure
650 | ```json
651 | {
652 | "user_id": "uuid",
653 | "email": "[email protected]",
654 | "roles": ["user"],
655 | "exp": 1234567890,
656 | "iat": 1234567890
657 | }
658 | ```
659 |
660 | ## Relations
661 | - implemented_by [[Authentication Service]]
662 | - requires [[User Database Schema]]
663 | - part_of [[Security Architecture]]
664 | - extends [[OAuth 2.0 Spec]]
665 | """,
666 | folder="specs",
667 | tags=["spec", "auth", "security"],
668 | entity_type="spec",
669 | project="main"
670 | )
671 | ```
672 |
673 | ### Tags Strategy
674 |
675 | **Effective tagging**:
676 |
677 | ```python
678 | # Technology tags
679 | #python #fastapi #graphql #postgresql
680 |
681 | # Domain tags
682 | #auth #security #api #frontend #backend
683 |
684 | # Status tags
685 | #wip #completed #deprecated #planned
686 |
687 | # Priority tags
688 | #urgent #important #nice-to-have
689 |
690 | # Category tags
691 | #bug #feature #refactor #docs #test
692 | ```
693 |
694 | **Example with strategic tags**:
695 |
696 | ```python
697 | await write_note(
698 | title="OAuth Integration",
699 | content="""# OAuth Integration
700 |
701 | ## Observations
702 | - [feature] Google OAuth integration completed #oauth #google #completed
703 | - [feature] GitHub OAuth in progress #oauth #github #wip
704 | - [requirement] Add Microsoft OAuth support #oauth #microsoft #planned
705 | - [technique] Using authlib for OAuth flow #python #authlib
706 | - [insight] OAuth reduces password reset requests by 80% #metrics #security
707 | """,
708 | folder="features",
709 | tags=["oauth", "authentication", "integration"],
710 | project="main"
711 | )
712 | ```
713 |
714 | ---
715 |
716 | ## Reading and Navigation
717 |
718 | **Reading notes and navigating the knowledge graph is fundamental to building context.**
719 |
720 | ### Reading by Identifier
721 |
722 | **Read by title**:
723 |
724 | ```python
725 | # Simple title
726 | note = await read_note(
727 | identifier="Authentication System",
728 | project="main"
729 | )
730 |
731 | # Title in specific folder
732 | note = await read_note(
733 | identifier="specs/Authentication System",
734 | project="main"
735 | )
736 | ```
737 |
738 | **Read by permalink**:
739 |
740 | ```python
741 | # Permalink is auto-generated from title
742 | note = await read_note(
743 | identifier="authentication-system",
744 | project="main"
745 | )
746 |
747 | # Permalink with folder
748 | note = await read_note(
749 | identifier="specs/authentication-system",
750 | project="main"
751 | )
752 | ```
753 |
754 | ### Reading by memory:// URL
755 |
756 | **URL formats**:
757 |
758 | ```python
759 | # By title
760 | note = await read_note(
761 | identifier="memory://Authentication System",
762 | project="main"
763 | )
764 |
765 | # By folder and title
766 | note = await read_note(
767 | identifier="memory://specs/Authentication System",
768 | project="main"
769 | )
770 |
771 | # By permalink
772 | note = await read_note(
773 | identifier="memory://authentication-system",
774 | project="main"
775 | )
776 |
777 | # Wildcards for folder contents
778 | notes = await read_note(
779 | identifier="memory://specs/*",
780 | project="main"
781 | )
782 | ```
783 |
784 | ```python
785 | # Underscores automatically converted to hyphens
786 | note = await read_note(
787 | identifier="memory://my_note_title",
788 | project="main"
789 | )
790 | # Finds entity with permalink "my-note-title"
791 |
792 | # Both forms work
793 | note1 = await read_note("memory://api_design", project="main")
794 | note2 = await read_note("memory://api-design", project="main")
795 | # Both find same entity
796 | ```
797 |
798 | ### Response Structure
799 |
800 | **read_note response includes**:
801 |
802 | ```python
803 | {
804 | "title": "Authentication System",
805 | "permalink": "authentication-system",
806 | "content": "# Authentication System\n\n...",
807 | "folder": "specs",
808 | "tags": ["auth", "security"],
809 | "type": "spec",
810 | "created": "2025-01-10T14:30:00Z",
811 | "updated": "2025-01-15T09:15:00Z",
812 | "observations": [
813 | {
814 | "category": "decision",
815 | "content": "Use JWT for authentication",
816 | "tags": ["security"]
817 | }
818 | ],
819 | "relations": [
820 | {
821 | "type": "implemented_by",
822 | "target": "Authentication Service",
823 | "target_permalink": "authentication-service"
824 | }
825 | ]
826 | }
827 | ```
828 |
829 | ### Pagination
830 |
831 | **For long notes, use pagination**:
832 |
833 | ```python
834 | # First page (default: 10 items)
835 | page1 = await read_note(
836 | identifier="Long Document",
837 | page=1,
838 | page_size=10,
839 | project="main"
840 | )
841 |
842 | # Second page
843 | page2 = await read_note(
844 | identifier="Long Document",
845 | page=2,
846 | page_size=10,
847 | project="main"
848 | )
849 |
850 | # Large page size for complete content
851 | full = await read_note(
852 | identifier="Long Document",
853 | page=1,
854 | page_size=1000,
855 | project="main"
856 | )
857 | ```
858 |
859 | ### Reading Raw Content
860 |
861 | **For non-markdown files or raw access**:
862 |
863 | ```python
864 | # Read text file
865 | content = await read_content(
866 | path="config/settings.json",
867 | project="main"
868 | )
869 |
870 | # Read image (returned as base64)
871 | image = await read_content(
872 | path="diagrams/architecture.png",
873 | project="main"
874 | )
875 |
876 | # Read any file type
877 | data = await read_content(
878 | path="data/export.csv",
879 | project="main"
880 | )
881 | ```
882 |
883 | **Difference from read_note**:
884 | - `read_note`: Parses markdown, extracts knowledge graph
885 | - `read_content`: Returns raw file content
886 | - Use `read_note` for knowledge graph navigation
887 | - Use `read_content` for non-markdown files
888 |
889 | ### Viewing as Artifact
890 |
891 | **For better readability, use view_note**:
892 |
893 | ```python
894 | # Display as formatted artifact
895 | artifact = await view_note(
896 | identifier="Authentication System",
897 | project="main"
898 | )
899 |
900 | # Returns formatted markdown suitable for display
901 | # - Syntax highlighting
902 | # - Rendered markdown
903 | # - Better visual presentation
904 | ```
905 |
906 | **When to use view_note**:
907 | - Showing content to user
908 | - Presenting documentation
909 | - Displaying specifications
910 | - Better than raw markdown for reading
911 |
912 | ### Directory Browsing
913 |
914 | **List directory contents**:
915 |
916 | ```python
917 | # List top-level folders
918 | root = await list_directory(
919 | dir_name="/",
920 | project="main"
921 | )
922 |
923 | # List specific folder
924 | specs = await list_directory(
925 | dir_name="specs",
926 | project="main"
927 | )
928 |
929 | # Recursive listing
930 | all_files = await list_directory(
931 | dir_name="/",
932 | depth=3,
933 | project="main"
934 | )
935 |
936 | # Filter by pattern
937 | markdown_files = await list_directory(
938 | dir_name="docs",
939 | file_name_glob="*.md",
940 | project="main"
941 | )
942 | ```
943 |
944 | **Response structure**:
945 |
946 | ```python
947 | {
948 | "path": "specs",
949 | "files": [
950 | {
951 | "name": "authentication-system.md",
952 | "path": "specs/authentication-system.md",
953 | "type": "file",
954 | "size": 2048,
955 | "modified": "2025-01-15T09:15:00Z"
956 | }
957 | ],
958 | "directories": [
959 | {
960 | "name": "api",
961 | "path": "specs/api",
962 | "type": "directory",
963 | "file_count": 5
964 | }
965 | ]
966 | }
967 | ```
968 |
969 | ---
970 |
971 | ## Search and Discovery
972 |
973 | **Search is the primary way to discover relevant knowledge.**
974 |
975 | ### Basic Search
976 |
977 | **Simple text search**:
978 |
979 | ```python
980 | # Search across all content
981 | results = await search_notes(
982 | query="authentication",
983 | project="main"
984 | )
985 |
986 | # Search with pagination
987 | results = await search_notes(
988 | query="authentication",
989 | page=1,
990 | page_size=10,
991 | project="main"
992 | )
993 |
994 | # Get more results
995 | results = await search_notes(
996 | query="authentication",
997 | page=1,
998 | page_size=50,
999 | project="main"
1000 | )
1001 | ```
1002 |
1003 | ### Advanced Search
1004 |
1005 | **Filter by entity type**:
1006 |
1007 | ```python
1008 | # Search only specifications
1009 | specs = await search_notes(
1010 | query="authentication",
1011 | types=["spec"],
1012 | project="main"
1013 | )
1014 |
1015 | # Search decisions and meetings
1016 | decisions = await search_notes(
1017 | query="api design",
1018 | types=["decision", "meeting"],
1019 | project="main"
1020 | )
1021 | ```
1022 |
1023 | **Filter by observation category**:
1024 |
1025 | ```python
1026 | # Find all decisions
1027 | decisions = await search_notes(
1028 | query="",
1029 | entity_types=["decision"],
1030 | project="main"
1031 | )
1032 |
1033 | # Find problems and solutions
1034 | issues = await search_notes(
1035 | query="performance",
1036 | entity_types=["problem", "solution"],
1037 | project="main"
1038 | )
1039 | ```
1040 |
1041 | **Date filtering**:
1042 |
1043 | ```python
1044 | # Find recent changes
1045 | recent = await search_notes(
1046 | query="api",
1047 | after_date="2025-01-01",
1048 | project="main"
1049 | )
1050 |
1051 | # Combine with other filters
1052 | recent_decisions = await search_notes(
1053 | query="authentication",
1054 | types=["decision"],
1055 | after_date="2025-01-01",
1056 | project="main"
1057 | )
1058 | ```
1059 |
1060 | ### Search Types
1061 |
1062 | **Text search (default)**:
1063 |
1064 | ```python
1065 | # Full-text search across all content
1066 | results = await search_notes(
1067 | query="JWT authentication",
1068 | search_type="text",
1069 | project="main"
1070 | )
1071 | ```
1072 |
1073 | **Semantic search**:
1074 |
1075 | ```python
1076 | # Semantic/vector search (if enabled)
1077 | results = await search_notes(
1078 | query="user login security",
1079 | search_type="semantic",
1080 | project="main"
1081 | )
1082 | ```
1083 |
1084 | ### Search Response
1085 |
1086 | **Result structure**:
1087 |
1088 | ```python
1089 | {
1090 | "results": [
1091 | {
1092 | "title": "Authentication System",
1093 | "permalink": "authentication-system",
1094 | "folder": "specs",
1095 | "snippet": "...JWT authentication for user login...",
1096 | "score": 0.95,
1097 | "tags": ["auth", "security"],
1098 | "type": "spec",
1099 | "updated": "2025-01-15T09:15:00Z"
1100 | }
1101 | ],
1102 | "total": 15,
1103 | "page": 1,
1104 | "page_size": 10,
1105 | "has_more": true
1106 | }
1107 | ```
1108 |
1109 | ### Search Strategies
1110 |
1111 | **Broad to narrow**:
1112 |
1113 | ```python
1114 | # Start broad
1115 | all_auth = await search_notes(
1116 | query="authentication",
1117 | project="main"
1118 | )
1119 |
1120 | # Narrow down
1121 | jwt_auth = await search_notes(
1122 | query="JWT authentication",
1123 | types=["spec", "decision"],
1124 | project="main"
1125 | )
1126 |
1127 | # Very specific
1128 | recent_jwt = await search_notes(
1129 | query="JWT token implementation",
1130 | types=["spec"],
1131 | after_date="2025-01-01",
1132 | project="main"
1133 | )
1134 | ```
1135 |
1136 | **Find related content**:
1137 |
1138 | ```python
1139 | # 1. Search for main topic
1140 | auth_notes = await search_notes(
1141 | query="authentication",
1142 | project="main"
1143 | )
1144 |
1145 | # 2. Read top result
1146 | main_note = await read_note(
1147 | identifier=auth_notes["results"][0]["permalink"],
1148 | project="main"
1149 | )
1150 |
1151 | # 3. Build context from relations
1152 | context = await build_context(
1153 | url=f"memory://{main_note['permalink']}",
1154 | depth=2,
1155 | project="main"
1156 | )
1157 |
1158 | # 4. Search for related terms from relations
1159 | for relation in main_note["relations"]:
1160 | related = await search_notes(
1161 | query=relation["target"],
1162 | project="main"
1163 | )
1164 | ```
1165 |
1166 | **Multi-faceted search**:
1167 |
1168 | ```python
1169 | # Search by different aspects
1170 | by_topic = await search_notes(query="API design", project="main")
1171 | by_author = await search_notes(query="Alice", project="main")
1172 | by_date = await search_notes(query="", after_date="2025-01-15", project="main")
1173 | by_tag = await search_notes(query="#security", project="main")
1174 | by_type = await search_notes(query="", types=["decision"], project="main")
1175 |
1176 | # Combine for precision
1177 | precise = await search_notes(
1178 | query="API security",
1179 | types=["decision"],
1180 | after_date="2025-01-01",
1181 | project="main"
1182 | )
1183 | ```
1184 |
1185 | ---
1186 |
1187 | ## Building Context
1188 |
1189 | **Context building enables conversation continuity by traversing the knowledge graph.**
1190 |
1191 | ### Basic Context Building
1192 |
1193 | **Simple context**:
1194 |
1195 | ```python
1196 | # Build context from entity
1197 | context = await build_context(
1198 | url="memory://Authentication System",
1199 | project="main"
1200 | )
1201 |
1202 | # Returns:
1203 | # - The root entity
1204 | # - Directly related entities
1205 | # - Recent observations
1206 | # - Connection paths
1207 | ```
1208 |
1209 | ### Depth Control
1210 |
1211 | **Shallow context (depth=1)**:
1212 |
1213 | ```python
1214 | # Only immediate connections
1215 | shallow = await build_context(
1216 | url="memory://Authentication System",
1217 | depth=1,
1218 | project="main"
1219 | )
1220 |
1221 | # Returns:
1222 | # - Root entity
1223 | # - Entities with direct relations
1224 | # - First-degree connections only
1225 | ```
1226 |
1227 | **Deep context (depth=2)**:
1228 |
1229 | ```python
1230 | # Two levels of connections
1231 | deep = await build_context(
1232 | url="memory://Authentication System",
1233 | depth=2,
1234 | project="main"
1235 | )
1236 |
1237 | # Returns:
1238 | # - Root entity
1239 | # - Direct relations (depth 1)
1240 | # - Relations of relations (depth 2)
1241 | # - More comprehensive context
1242 | ```
1243 |
1244 | **Very deep context (depth=3+)**:
1245 |
1246 | ```python
1247 | # Three or more levels
1248 | very_deep = await build_context(
1249 | url="memory://Authentication System",
1250 | depth=3,
1251 | project="main"
1252 | )
1253 |
1254 | # Warning: Can return a lot of data
1255 | # Use for comprehensive understanding
1256 | # May be slow for large graphs
1257 | ```
1258 |
1259 | ### Timeframe Filtering
1260 |
1261 | **Recent context**:
1262 |
1263 | ```python
1264 | # Last 7 days
1265 | recent = await build_context(
1266 | url="memory://Authentication System",
1267 | timeframe="7d",
1268 | project="main"
1269 | )
1270 |
1271 | # Natural language timeframes
1272 | last_week = await build_context(
1273 | url="memory://API Design",
1274 | timeframe="1 week",
1275 | project="main"
1276 | )
1277 |
1278 | last_month = await build_context(
1279 | url="memory://Project Planning",
1280 | timeframe="30 days",
1281 | project="main"
1282 | )
1283 |
1284 | # Minimum: 1 day (enforced since v0.15.0)
1285 | ```
1286 |
1287 | **All-time context**:
1288 |
1289 | ```python
1290 | # No timeframe = all history
1291 | complete = await build_context(
1292 | url="memory://Authentication System",
1293 | depth=2,
1294 | project="main"
1295 | )
1296 | ```
1297 |
1298 | ### Context Response Structure
1299 |
1300 | **Response includes**:
1301 |
1302 | ```python
1303 | {
1304 | "root_entity": {
1305 | "title": "Authentication System",
1306 | "permalink": "authentication-system",
1307 | "content": "...",
1308 | "observations": [...],
1309 | "relations": [...]
1310 | },
1311 | "related_entities": [
1312 | {
1313 | "title": "User Database",
1314 | "permalink": "user-database",
1315 | "relation_type": "requires",
1316 | "distance": 1,
1317 | "content": "...",
1318 | "observations": [...],
1319 | "relations": [...]
1320 | },
1321 | {
1322 | "title": "Login API",
1323 | "permalink": "login-api",
1324 | "relation_type": "implemented_by",
1325 | "distance": 1,
1326 | "content": "...",
1327 | "observations": [...],
1328 | "relations": [...]
1329 | }
1330 | ],
1331 | "paths": [
1332 | {
1333 | "from": "authentication-system",
1334 | "to": "login-api",
1335 | "path": [
1336 | {"entity": "authentication-system", "relation": "implemented_by"},
1337 | {"entity": "login-api"}
1338 | ]
1339 | }
1340 | ],
1341 | "summary": {
1342 | "total_entities": 5,
1343 | "total_relations": 8,
1344 | "max_depth": 2,
1345 | "timeframe": "7d"
1346 | }
1347 | }
1348 | ```
1349 |
1350 | ### Context Building Patterns
1351 |
1352 | **Continuing conversations**:
1353 |
1354 | ```python
1355 | # User: "Let's discuss authentication"
1356 |
1357 | # 1. Search for topic
1358 | results = await search_notes(
1359 | query="authentication",
1360 | project="main"
1361 | )
1362 |
1363 | # 2. Build context from most relevant
1364 | context = await build_context(
1365 | url=f"memory://{results['results'][0]['permalink']}",
1366 | depth=2,
1367 | timeframe="30d",
1368 | project="main"
1369 | )
1370 |
1371 | # 3. Use context to inform response
1372 | # "Based on our previous work on authentication, including
1373 | # the JWT implementation and OAuth integration..."
1374 | ```
1375 |
1376 | **Exploring knowledge areas**:
1377 |
1378 | ```python
1379 | # Start with broad topic
1380 | initial = await build_context(
1381 | url="memory://API Design",
1382 | depth=1,
1383 | project="main"
1384 | )
1385 |
1386 | # Explore interesting branches
1387 | for entity in initial["related_entities"]:
1388 | if "GraphQL" in entity["title"]:
1389 | graphql_context = await build_context(
1390 | url=f"memory://{entity['permalink']}",
1391 | depth=2,
1392 | project="main"
1393 | )
1394 | ```
1395 |
1396 | **Finding connection paths**:
1397 |
1398 | ```python
1399 | # Build context from both endpoints
1400 | start_context = await build_context(
1401 | url="memory://Frontend App",
1402 | depth=2,
1403 | project="main"
1404 | )
1405 |
1406 | end_context = await build_context(
1407 | url="memory://Database Schema",
1408 | depth=2,
1409 | project="main"
1410 | )
1411 |
1412 | # Analyze paths in response
1413 | # Shows how frontend connects to database through API layer
1414 | ```
1415 |
1416 | ---
1417 |
1418 | ## Recording Conversations
1419 |
1420 | **Capturing conversations in Basic Memory enables long-term context and knowledge accumulation.**
1421 |
1422 | ### Permission and Transparency
1423 |
1424 | **Always ask before recording**:
1425 |
1426 | ```
1427 | AI: "Would you like me to save our discussion about API authentication
1428 | to Basic Memory? This will help us continue this conversation later
1429 | and build on what we've learned."
1430 |
1431 | User: "Yes, please"
1432 |
1433 | AI: [Saves to Basic Memory]
1434 | "I've saved our discussion to Basic Memory as 'API Authentication Discussion'."
1435 | ```
1436 |
1437 | **Be transparent**:
1438 | - Ask permission before saving
1439 | - Confirm after saving
1440 | - Explain what was saved
1441 | - Mention how it helps future conversations
1442 |
1443 | **Your role**: As an AI collaborator, you're helping build knowledge that will outlast any particular AI model or session. Write observations and relations that will be valuable to the human (and future AI assistants) years from now. Think: enduring insights, not ephemeral chat logs. These plain-text markdown files are artifacts worth keeping - make them count.
1444 |
1445 | ### What to Record
1446 |
1447 | **Good candidates for recording**:
1448 |
1449 | 1. **Decisions and Rationales**
1450 | ```python
1451 | await write_note(
1452 | title="Decision: GraphQL vs REST",
1453 | content="""# Decision: GraphQL vs REST
1454 |
1455 | ## Context
1456 | User asked about API architecture choice.
1457 |
1458 | ## Decision
1459 | Chose GraphQL for new features, maintain REST for legacy.
1460 |
1461 | ## Observations
1462 | - [decision] GraphQL for flexibility and performance #api
1463 | - [requirement] Mobile app needs efficient data loading #mobile
1464 | - [fact] REST API has 50K existing clients #legacy
1465 | - [insight] Hybrid approach minimizes migration risk #strategy
1466 |
1467 | ## Relations
1468 | - implements [[API Modernization Plan]]
1469 | - affects [[Mobile Development]]
1470 | """,
1471 | folder="decisions",
1472 | project="main"
1473 | )
1474 | ```
1475 |
1476 | 2. **Important Discoveries**
1477 | ```python
1478 | await write_note(
1479 | title="Discovery: Database Performance Issue",
1480 | content="""# Discovery: Database Performance Issue
1481 |
1482 | ## Context
1483 | User reported slow login times.
1484 |
1485 | ## Observations
1486 | - [problem] Login queries taking 2-3 seconds #performance
1487 | - [insight] Missing index on users.email column #database
1488 | - [solution] Added index, login now <100ms #fix
1489 | - [technique] Used EXPLAIN ANALYZE to identify bottleneck #debugging
1490 | - [fact] 80% of queries were sequential scans #metrics
1491 |
1492 | ## Resolution
1493 | Created index on email column, query time improved 20x.
1494 |
1495 | ## Relations
1496 | - relates_to [[User Authentication]]
1497 | - caused_by [[Database Schema Migration]]
1498 | """,
1499 | folder="troubleshooting",
1500 | project="main"
1501 | )
1502 | ```
1503 |
1504 | 3. **Action Items and Plans**
1505 | ```python
1506 | await write_note(
1507 | title="Plan: API v2 Migration",
1508 | content="""# Plan: API v2 Migration
1509 |
1510 | ## Overview
1511 | Discussed migration strategy from REST v1 to GraphQL v2.
1512 |
1513 | ## Observations
1514 | - [plan] Phased migration over 3 months #roadmap
1515 | - [action] Create GraphQL schema this week #task
1516 | - [action] Implement parallel APIs next month #task
1517 | - [decision] Deprecate v1 after 6-month notice #timeline
1518 | - [requirement] Must maintain backward compatibility #constraint
1519 |
1520 | ## Timeline
1521 | - Week 1-2: Schema design
1522 | - Week 3-4: Core API implementation
1523 | - Month 2: Client migration support
1524 | - Month 3: Documentation and training
1525 |
1526 | ## Relations
1527 | - implements [[API Modernization Strategy]]
1528 | - requires [[GraphQL Schema Design]]
1529 | - affects [[All API Clients]]
1530 | """,
1531 | folder="planning",
1532 | project="main"
1533 | )
1534 | ```
1535 |
1536 | 4. **Connected Topics**
1537 | ```python
1538 | await write_note(
1539 | title="Conversation: Security Best Practices",
1540 | content="""# Conversation: Security Best Practices
1541 |
1542 | ## Discussion Summary
1543 | User asked about security measures for new API.
1544 |
1545 | ## Observations
1546 | - [recommendation] Implement rate limiting on all endpoints #security
1547 | - [technique] Use JWT with short expiry + refresh tokens #auth
1548 | - [requirement] HTTPS only in production #infrastructure
1549 | - [technique] Input validation with Pydantic schemas #validation
1550 | - [recommendation] Regular security audits quarterly #process
1551 |
1552 | ## Key Insights
1553 | - Defense in depth approach is essential
1554 | - Rate limiting prevents most automated attacks
1555 | - Token rotation improves security posture
1556 |
1557 | ## Related Topics
1558 | - Authentication mechanisms
1559 | - Authorization patterns
1560 | - Data encryption
1561 | - Audit logging
1562 |
1563 | ## Relations
1564 | - relates_to [[API Security Architecture]]
1565 | - implements [[Security Policy]]
1566 | - requires [[Rate Limiting Service]]
1567 | """,
1568 | folder="conversations",
1569 | project="main"
1570 | )
1571 | ```
1572 |
1573 | ### Recording Patterns
1574 |
1575 | **Conversation summary**:
1576 |
1577 | ```python
1578 | # After substantial discussion
1579 | await write_note(
1580 | title=f"Conversation: {topic} - {date}",
1581 | content=f"""# Conversation: {topic}
1582 |
1583 | ## Summary
1584 | {brief_summary}
1585 |
1586 | ## Key Points Discussed
1587 | {key_points}
1588 |
1589 | ## Observations
1590 | {categorized_observations}
1591 |
1592 | ## Decisions Made
1593 | {decisions}
1594 |
1595 | ## Action Items
1596 | {action_items}
1597 |
1598 | ## Relations
1599 | {relevant_relations}
1600 | """,
1601 | folder="conversations",
1602 | tags=["conversation", topic_tags],
1603 | project="main"
1604 | )
1605 | ```
1606 |
1607 | **Decision record**:
1608 |
1609 | ```python
1610 | # For important decisions
1611 | await write_note(
1612 | title=f"Decision: {decision_title}",
1613 | content=f"""# Decision: {decision_title}
1614 |
1615 | ## Context
1616 | {why_decision_needed}
1617 |
1618 | ## Decision
1619 | {what_was_decided}
1620 |
1621 | ## Observations
1622 | {categorized_observations}
1623 |
1624 | ## Rationale
1625 | {reasoning}
1626 |
1627 | ## Consequences
1628 | {implications}
1629 |
1630 | ## Relations
1631 | {related_entities}
1632 | """,
1633 | folder="decisions",
1634 | entity_type="decision",
1635 | project="main"
1636 | )
1637 | ```
1638 |
1639 | **Learning capture**:
1640 |
1641 | ```python
1642 | # For new knowledge or insights
1643 | await write_note(
1644 | title=f"Learning: {topic}",
1645 | content=f"""# Learning: {topic}
1646 |
1647 | ## What We Learned
1648 | {insights}
1649 |
1650 | ## Observations
1651 | {categorized_facts}
1652 |
1653 | ## How This Helps
1654 | {practical_applications}
1655 |
1656 | ## Relations
1657 | {connected_knowledge}
1658 | """,
1659 | folder="learnings",
1660 | project="main"
1661 | )
1662 | ```
1663 |
1664 | ### Building on Past Conversations
1665 |
1666 | **Reference previous discussions**:
1667 |
1668 | ```python
1669 | # 1. Search for related past conversations
1670 | past = await search_notes(
1671 | query="API authentication",
1672 | types=["conversation", "decision"],
1673 | project="main"
1674 | )
1675 |
1676 | # 2. Build context
1677 | context = await build_context(
1678 | url=f"memory://{past['results'][0]['permalink']}",
1679 | depth=2,
1680 | timeframe="30d",
1681 | project="main"
1682 | )
1683 |
1684 | # 3. Reference in new conversation
1685 | # "Building on our previous discussion about JWT authentication,
1686 | # let's now address the refresh token implementation..."
1687 |
1688 | # 4. Link new note to previous
1689 | await write_note(
1690 | title="Refresh Token Implementation",
1691 | content="""# Refresh Token Implementation
1692 |
1693 | ## Relations
1694 | - builds_on [[Conversation: API Authentication]]
1695 | - implements [[JWT Authentication Decision]]
1696 | """,
1697 | folder="implementation",
1698 | project="main"
1699 | )
1700 | ```
1701 |
1702 | ---
1703 |
1704 | ## Editing Notes
1705 |
1706 | **Edit existing notes incrementally without rewriting entire content.**
1707 |
1708 | ### Edit Operations
1709 |
1710 | **Available operations**:
1711 | - `append`: Add to end of note
1712 | - `prepend`: Add to beginning
1713 | - `find_replace`: Replace specific text
1714 | - `replace_section`: Replace markdown section
1715 |
1716 | ### Append Content
1717 |
1718 | **Add to end of note**:
1719 |
1720 | ```python
1721 | await edit_note(
1722 | identifier="Authentication System",
1723 | operation="append",
1724 | content="""
1725 |
1726 | ## New Section
1727 |
1728 | Additional information discovered.
1729 |
1730 | ## Observations
1731 | - [fact] New security requirement identified #security
1732 | """,
1733 | project="main"
1734 | )
1735 | ```
1736 |
1737 | **Use cases**:
1738 | - Adding new observations
1739 | - Appending related topics
1740 | - Adding follow-up information
1741 | - Extending discussions
1742 |
1743 | ### Prepend Content
1744 |
1745 | **Add to beginning of note**:
1746 |
1747 | ```python
1748 | await edit_note(
1749 | identifier="Meeting Notes",
1750 | operation="prepend",
1751 | content="""## Update
1752 |
1753 | Important development since meeting.
1754 |
1755 | ---
1756 |
1757 | """,
1758 | project="main"
1759 | )
1760 | ```
1761 |
1762 | **Use cases**:
1763 | - Adding urgent updates
1764 | - Inserting warnings
1765 | - Adding important context
1766 | - Prepending summaries
1767 |
1768 | ### Find and Replace
1769 |
1770 | **Replace specific text**:
1771 |
1772 | ```python
1773 | await edit_note(
1774 | identifier="API Documentation",
1775 | operation="find_replace",
1776 | find_text="http://api.example.com",
1777 | content="https://api.example.com",
1778 | expected_replacements=3,
1779 | project="main"
1780 | )
1781 | ```
1782 |
1783 | **With expected replacements count**:
1784 |
1785 | ```python
1786 | # Expects exactly 1 replacement
1787 | await edit_note(
1788 | identifier="Config File",
1789 | operation="find_replace",
1790 | find_text="DEBUG = True",
1791 | content="DEBUG = False",
1792 | expected_replacements=1,
1793 | project="main"
1794 | )
1795 |
1796 | # Error if count doesn't match
1797 | # Prevents unintended changes
1798 | ```
1799 |
1800 | **Use cases**:
1801 | - Updating URLs
1802 | - Correcting terminology
1803 | - Fixing typos
1804 | - Updating version numbers
1805 |
1806 | ### Replace Section
1807 |
1808 | **Replace markdown section by heading**:
1809 |
1810 | ```python
1811 | await edit_note(
1812 | identifier="Project Status",
1813 | operation="replace_section",
1814 | section="## Current Status",
1815 | content="""## Current Status
1816 |
1817 | Project completed successfully.
1818 |
1819 | All milestones achieved ahead of schedule.
1820 | """,
1821 | project="main"
1822 | )
1823 | ```
1824 |
1825 | **Replace nested section**:
1826 |
1827 | ```python
1828 | await edit_note(
1829 | identifier="Technical Docs",
1830 | operation="replace_section",
1831 | section="### Authentication", # Finds h3 heading
1832 | content="""### Authentication
1833 |
1834 | Updated authentication flow using OAuth 2.0.
1835 |
1836 | See [[OAuth Implementation]] for details.
1837 | """,
1838 | project="main"
1839 | )
1840 | ```
1841 |
1842 | **Use cases**:
1843 | - Updating status sections
1844 | - Replacing outdated information
1845 | - Modifying specific topics
1846 | - Restructuring content
1847 |
1848 | ### Adding Observations
1849 |
1850 | **Append new observations**:
1851 |
1852 | ```python
1853 | # Read current note
1854 | note = await read_note("API Design", project="main")
1855 |
1856 | # Add new observations
1857 | await edit_note(
1858 | identifier="API Design",
1859 | operation="append",
1860 | content="""
1861 | - [insight] GraphQL reduces API calls by 60% #performance
1862 | - [decision] Implement query complexity limiting #security
1863 | - [action] Document schema changes weekly #documentation
1864 | """,
1865 | project="main"
1866 | )
1867 | ```
1868 |
1869 | ### Adding Relations
1870 |
1871 | **Append new relations**:
1872 |
1873 | ```python
1874 | await edit_note(
1875 | identifier="Authentication System",
1876 | operation="append",
1877 | content="""
1878 | - integrates_with [[OAuth Provider]]
1879 | - requires [[Rate Limiting Service]]
1880 | """,
1881 | project="main"
1882 | )
1883 | ```
1884 |
1885 | **Update relations section**:
1886 |
1887 | ```python
1888 | await edit_note(
1889 | identifier="API Backend",
1890 | operation="replace_section",
1891 | section="## Relations",
1892 | content="""## Relations
1893 | - implements [[API Specification v2]]
1894 | - requires [[Database Layer]]
1895 | - integrates_with [[Authentication Service]]
1896 | - monitored_by [[Logging System]]
1897 | - deployed_to [[Production Infrastructure]]
1898 | """,
1899 | project="main"
1900 | )
1901 | ```
1902 |
1903 | ### Bulk Updates
1904 |
1905 | **Update multiple notes**:
1906 |
1907 | ```python
1908 | # Search for notes to update
1909 | notes = await search_notes(
1910 | query="deprecated",
1911 | project="main"
1912 | )
1913 |
1914 | # Update each note
1915 | for note in notes["results"]:
1916 | await edit_note(
1917 | identifier=note["permalink"],
1918 | operation="prepend",
1919 | content="⚠️ **DEPRECATED** - See [[New Implementation]]\n\n---\n\n",
1920 | project="main"
1921 | )
1922 | ```
1923 |
1924 | ### Collaborative Editing
1925 |
1926 | **Track changes and updates**:
1927 |
1928 | ```python
1929 | # Add update log
1930 | await edit_note(
1931 | identifier="Living Document",
1932 | operation="append",
1933 | content=f"""
1934 |
1935 | ## Update Log
1936 |
1937 | ### {current_date}
1938 | - Updated authentication section
1939 | - Added OAuth examples
1940 | - Fixed broken links
1941 |
1942 | """,
1943 | project="main"
1944 | )
1945 | ```
1946 |
1947 | ---
1948 |
1949 | ## Moving and Organizing
1950 |
1951 | **Organize notes by moving them between folders while maintaining knowledge graph integrity.**
1952 |
1953 | ### Basic Move
1954 |
1955 | **Move to new folder**:
1956 |
1957 | ```python
1958 | await move_note(
1959 | identifier="API Documentation",
1960 | destination_path="docs/api/api-documentation.md",
1961 | project="main"
1962 | )
1963 | ```
1964 |
1965 | **Move with auto-extension**:
1966 |
1967 | ```python
1968 | # Both work (v0.15.0+)
1969 | await move_note(
1970 | identifier="Note",
1971 | destination_path="new-folder/note.md",
1972 | project="main"
1973 | )
1974 |
1975 | await move_note(
1976 | identifier="Note",
1977 | destination_path="new-folder/note", # .md added automatically
1978 | project="main"
1979 | )
1980 | ```
1981 |
1982 | ### Organizing Knowledge
1983 |
1984 | **Create folder structure**:
1985 |
1986 | ```python
1987 | # Move related notes to dedicated folders
1988 |
1989 | # Move specs
1990 | await move_note("Authentication Spec", "specs/auth/authentication.md", project="main")
1991 | await move_note("API Spec", "specs/api/api-spec.md", project="main")
1992 |
1993 | # Move implementations
1994 | await move_note("Auth Service", "services/auth/auth-service.md", project="main")
1995 | await move_note("API Server", "services/api/api-server.md", project="main")
1996 |
1997 | # Move decisions
1998 | await move_note("Decision: OAuth", "decisions/oauth-decision.md", project="main")
1999 |
2000 | # Move meetings
2001 | await move_note("API Review 2025-01-15", "meetings/2025/01/api-review.md", project="main")
2002 | ```
2003 |
2004 | **Folder hierarchy**:
2005 |
2006 | ```
2007 | project/
2008 | ├── specs/
2009 | │ ├── auth/
2010 | │ └── api/
2011 | ├── services/
2012 | │ ├── auth/
2013 | │ └── api/
2014 | ├── decisions/
2015 | ├── meetings/
2016 | │ └── 2025/
2017 | │ └── 01/
2018 | ├── conversations/
2019 | └── learnings/
2020 | ```
2021 |
2022 | ### Batch Organization
2023 |
2024 | **Organize multiple notes**:
2025 |
2026 | ```python
2027 | # Get all auth-related notes
2028 | auth_notes = await search_notes(
2029 | query="authentication",
2030 | project="main"
2031 | )
2032 |
2033 | # Move to auth folder
2034 | for note in auth_notes["results"]:
2035 | if note["type"] == "spec":
2036 | await move_note(
2037 | identifier=note["permalink"],
2038 | destination_path=f"specs/auth/{note['permalink']}.md",
2039 | project="main"
2040 | )
2041 | elif note["type"] == "decision":
2042 | await move_note(
2043 | identifier=note["permalink"],
2044 | destination_path=f"decisions/auth/{note['permalink']}.md",
2045 | project="main"
2046 | )
2047 | ```
2048 |
2049 | ### Preserving Relations
2050 |
2051 | **Relations are automatically updated**:
2052 |
2053 | ```python
2054 | # Before move:
2055 | # Note A (folder: root) -> relates_to [[Note B]]
2056 | # Note B (folder: root)
2057 |
2058 | # Move Note B
2059 | await move_note(
2060 | identifier="Note B",
2061 | destination_path="subfolder/note-b.md",
2062 | project="main"
2063 | )
2064 |
2065 | # After move:
2066 | # Note A (folder: root) -> relates_to [[Note B]]
2067 | # Note B (folder: subfolder) <- relation still works!
2068 | # Database updated automatically
2069 | ```
2070 |
2071 | ### Renaming
2072 |
2073 | **Move to rename**:
2074 |
2075 | ```python
2076 | # Rename by moving to same folder with new name
2077 | await move_note(
2078 | identifier="Old Name",
2079 | destination_path="same-folder/new-name.md",
2080 | project="main"
2081 | )
2082 |
2083 | # Title and permalink updated
2084 | # Relations preserved
2085 | ```
2086 |
2087 | ### Archiving
2088 |
2089 | **Move to archive folder**:
2090 |
2091 | ```python
2092 | # Archive old notes
2093 | await move_note(
2094 | identifier="Deprecated Feature",
2095 | destination_path="archive/deprecated/deprecated-feature.md",
2096 | project="main"
2097 | )
2098 |
2099 | # Batch archive by date
2100 | old_notes = await search_notes(
2101 | query="",
2102 | after_date="2024-01-01",
2103 | project="main"
2104 | )
2105 |
2106 | for note in old_notes["results"]:
2107 | if note["updated"] < "2024-06-01":
2108 | await move_note(
2109 | identifier=note["permalink"],
2110 | destination_path=f"archive/2024/{note['permalink']}.md",
2111 | project="main"
2112 | )
2113 | ```
2114 |
2115 | ---
2116 |
2117 | ## Error Handling
2118 |
2119 | **Robust error handling ensures reliable AI-human interaction.**
2120 |
2121 | ### Missing Project Parameter
2122 |
2123 | **Error**: Tool called without project parameter
2124 |
2125 | **Solution**:
2126 |
2127 | ```python
2128 | try:
2129 | results = await search_notes(query="test")
2130 | except:
2131 | # Show available projects
2132 | projects = await list_memory_projects()
2133 |
2134 | # Ask user which to use
2135 | # "I need to know which project to search. Available projects: ..."
2136 |
2137 | # Retry with project
2138 | results = await search_notes(query="test", project="main")
2139 | ```
2140 |
2141 | **Prevention**:
2142 |
2143 | ```python
2144 | # Always discover projects first
2145 | projects = await list_memory_projects()
2146 |
2147 | # Store active project for session
2148 | active_project = projects[0]["name"]
2149 |
2150 | # Use in all calls
2151 | results = await search_notes(query="test", project=active_project)
2152 | ```
2153 |
2154 | ### Entity Not Found
2155 |
2156 | **Error**: Note doesn't exist
2157 |
2158 | **Solution**:
2159 |
2160 | ```python
2161 | try:
2162 | note = await read_note("Nonexistent Note", project="main")
2163 | except:
2164 | # Search for similar
2165 | results = await search_notes(query="Note", project="main")
2166 |
2167 | # Suggest alternatives
2168 | # "I couldn't find 'Nonexistent Note'. Did you mean:"
2169 | # - Similar Note 1
2170 | # - Similar Note 2
2171 | ```
2172 |
2173 | ### Forward Reference Resolution
2174 |
2175 | **Not an error**: Forward references resolve automatically
2176 |
2177 | ```python
2178 | # Create note with forward reference
2179 | response = await write_note(
2180 | title="Implementation",
2181 | content="## Relations\n- implements [[Future Spec]]",
2182 | folder="code",
2183 | project="main"
2184 | )
2185 |
2186 | # Response may indicate unresolved reference
2187 | # This is OK - will resolve when target created
2188 |
2189 | # Later, create target
2190 | await write_note(
2191 | title="Future Spec",
2192 | content="# Future Spec\n...",
2193 | folder="specs",
2194 | project="main"
2195 | )
2196 |
2197 | # Reference automatically resolved
2198 | # No action needed
2199 | ```
2200 |
2201 | ### Sync Status Issues
2202 |
2203 | **Error**: Data not found, sync in progress
2204 |
2205 | **Solution**:
2206 |
2207 | ```python
2208 | # Check sync status
2209 | status = await sync_status(project="main")
2210 |
2211 | if status["sync_in_progress"]:
2212 | # Inform user
2213 | # "The knowledge base is still syncing. Please wait..."
2214 |
2215 | # Wait or proceed with available data
2216 | # Can still search/read synced content
2217 | else:
2218 | # Sync complete, proceed normally
2219 | results = await search_notes(query="topic", project="main")
2220 | ```
2221 |
2222 | ### Ambiguous References
2223 |
2224 | **Error**: Multiple entities match
2225 |
2226 | **Solution**:
2227 |
2228 | ```python
2229 | # Ambiguous title
2230 | try:
2231 | note = await read_note("API", project="main")
2232 | except:
2233 | # Search to disambiguate
2234 | results = await search_notes(query="API", project="main")
2235 |
2236 | # Show options to user
2237 | # "Multiple notes found with 'API':"
2238 | # - API Specification (specs/)
2239 | # - API Implementation (services/)
2240 | # - API Documentation (docs/)
2241 |
2242 | # Use specific identifier
2243 | note = await read_note("specs/API Specification", project="main")
2244 | ```
2245 |
2246 | ### Empty Search Results
2247 |
2248 | **Not an error**: No matches found
2249 |
2250 | **Solution**:
2251 |
2252 | ```python
2253 | results = await search_notes(query="rare topic", project="main")
2254 |
2255 | if results["total"] == 0:
2256 | # Broaden search
2257 | broader = await search_notes(query="topic", project="main")
2258 |
2259 | # Or suggest creating note
2260 | # "No notes found about 'rare topic'. Would you like me to create one?"
2261 | ```
2262 |
2263 | ### Project Not Found
2264 |
2265 | **Error**: Specified project doesn't exist
2266 |
2267 | **Solution**:
2268 |
2269 | ```python
2270 | try:
2271 | results = await search_notes(query="test", project="nonexistent")
2272 | except:
2273 | # List available projects
2274 | projects = await list_memory_projects()
2275 |
2276 | # Show to user
2277 | # "Project 'nonexistent' not found. Available projects:"
2278 | # - main
2279 | # - work
2280 |
2281 | # Offer to create
2282 | # "Would you like to create a new project called 'nonexistent'?"
2283 | ```
2284 |
2285 | ### Edit Conflicts
2286 |
2287 | **Error**: find_replace didn't match expected count
2288 |
2289 | **Solution**:
2290 |
2291 | ```python
2292 | try:
2293 | await edit_note(
2294 | identifier="Config",
2295 | operation="find_replace",
2296 | find_text="old_value",
2297 | content="new_value",
2298 | expected_replacements=1,
2299 | project="main"
2300 | )
2301 | except:
2302 | # Read note to check
2303 | note = await read_note("Config", project="main")
2304 |
2305 | # Verify text exists
2306 | if "old_value" in note["content"]:
2307 | count = note["content"].count("old_value")
2308 | # Inform user: "Found {count} occurrences, expected 1"
2309 |
2310 | # Adjust or use replace_all
2311 | await edit_note(
2312 | identifier="Config",
2313 | operation="find_replace",
2314 | find_text="old_value",
2315 | content="new_value",
2316 | replace_all=True,
2317 | project="main"
2318 | )
2319 | ```
2320 |
2321 | ### Permission Errors
2322 |
2323 | **Error**: Can't write to destination
2324 |
2325 | **Solution**:
2326 |
2327 | ```python
2328 | try:
2329 | await move_note(
2330 | identifier="Note",
2331 | destination_path="/restricted/note.md",
2332 | project="main"
2333 | )
2334 | except:
2335 | # Inform user about permission issue
2336 | # "Cannot move note to /restricted/ - permission denied"
2337 |
2338 | # Suggest alternative
2339 | # "Try moving to a folder within the project directory"
2340 |
2341 | # Use valid path
2342 | await move_note(
2343 | identifier="Note",
2344 | destination_path="archive/note.md",
2345 | project="main"
2346 | )
2347 | ```
2348 |
2349 | ---
2350 |
2351 | ## Advanced Patterns
2352 |
2353 | **Sophisticated techniques for knowledge management and AI collaboration.**
2354 |
2355 | ### Knowledge Graph Visualization
2356 |
2357 | **Create visual representation using canvas**:
2358 |
2359 | ```python
2360 | # Gather entities to visualize
2361 | auth_context = await build_context(
2362 | url="memory://Authentication System",
2363 | depth=2,
2364 | project="main"
2365 | )
2366 |
2367 | # Create nodes
2368 | nodes = [
2369 | {
2370 | "id": "auth-system",
2371 | "type": "file",
2372 | "file": "specs/authentication-system.md",
2373 | "x": 0,
2374 | "y": 0,
2375 | "width": 400,
2376 | "height": 300
2377 | },
2378 | {
2379 | "id": "user-db",
2380 | "type": "file",
2381 | "file": "services/user-database.md",
2382 | "x": 500,
2383 | "y": 0,
2384 | "width": 400,
2385 | "height": 300
2386 | },
2387 | {
2388 | "id": "login-api",
2389 | "type": "file",
2390 | "file": "api/login-api.md",
2391 | "x": 250,
2392 | "y": 400,
2393 | "width": 400,
2394 | "height": 300
2395 | }
2396 | ]
2397 |
2398 | # Create edges showing relations
2399 | edges = [
2400 | {
2401 | "id": "edge-1",
2402 | "fromNode": "auth-system",
2403 | "toNode": "user-db",
2404 | "label": "requires"
2405 | },
2406 | {
2407 | "id": "edge-2",
2408 | "fromNode": "auth-system",
2409 | "toNode": "login-api",
2410 | "label": "implemented_by"
2411 | }
2412 | ]
2413 |
2414 | # Generate canvas
2415 | canvas = await canvas(
2416 | nodes=nodes,
2417 | edges=edges,
2418 | title="Authentication System Overview",
2419 | folder="diagrams",
2420 | project="main"
2421 | )
2422 |
2423 | # Opens in Obsidian for interactive exploration
2424 | ```
2425 |
2426 | ### Progressive Knowledge Building
2427 |
2428 | **Build knowledge incrementally over time**:
2429 |
2430 | ```python
2431 | # Session 1: Create foundation
2432 | await write_note(
2433 | title="API Design",
2434 | content="""# API Design
2435 |
2436 | ## Observations
2437 | - [requirement] Need REST API for mobile app
2438 |
2439 | ## Relations
2440 | - relates_to [[Mobile Development]]
2441 | """,
2442 | folder="planning",
2443 | project="main"
2444 | )
2445 |
2446 | # Session 2: Add details
2447 | await edit_note(
2448 | identifier="API Design",
2449 | operation="append",
2450 | content="""
2451 | - [decision] Using FastAPI framework #python
2452 | - [technique] Auto-generate OpenAPI docs
2453 | """,
2454 | project="main"
2455 | )
2456 |
2457 | # Session 3: Add related entities
2458 | await write_note(
2459 | title="API Authentication",
2460 | content="""# API Authentication
2461 |
2462 | ## Relations
2463 | - part_of [[API Design]]
2464 | """,
2465 | folder="specs",
2466 | project="main"
2467 | )
2468 |
2469 | # Update original with relation
2470 | await edit_note(
2471 | identifier="API Design",
2472 | operation="append",
2473 | content="""
2474 | - includes [[API Authentication]]
2475 | """,
2476 | project="main"
2477 | )
2478 |
2479 | # Session 4: Add implementation
2480 | await write_note(
2481 | title="API Implementation",
2482 | content="""# API Implementation
2483 |
2484 | ## Relations
2485 | - implements [[API Design]]
2486 | """,
2487 | folder="code",
2488 | project="main"
2489 | )
2490 | ```
2491 |
2492 | ### Cross-Project Knowledge Transfer
2493 |
2494 | **Transfer knowledge between projects**:
2495 |
2496 | ```python
2497 | # Read from source project
2498 | template = await read_note(
2499 | identifier="API Architecture Template",
2500 | project="templates"
2501 | )
2502 |
2503 | # Adapt for target project
2504 | adapted_content = template["content"].replace(
2505 | "{{PROJECT_NAME}}",
2506 | "New Project"
2507 | )
2508 |
2509 | # Write to target project
2510 | await write_note(
2511 | title="API Architecture",
2512 | content=adapted_content,
2513 | folder="architecture",
2514 | project="new-project"
2515 | )
2516 | ```
2517 |
2518 | ### Knowledge Graph Traversal
2519 |
2520 | **Traverse graph to discover insights**:
2521 |
2522 | ```python
2523 | # Start with entry point
2524 | start = await read_note("Product Roadmap", project="main")
2525 |
2526 | # Traverse relations
2527 | visited = set()
2528 | to_visit = [start["permalink"]]
2529 | all_related = []
2530 |
2531 | while to_visit:
2532 | current = to_visit.pop(0)
2533 | if current in visited:
2534 | continue
2535 |
2536 | visited.add(current)
2537 | note = await read_note(current, project="main")
2538 | all_related.append(note)
2539 |
2540 | # Add related entities to queue
2541 | for relation in note["relations"]:
2542 | if relation["target_permalink"] not in visited:
2543 | to_visit.append(relation["target_permalink"])
2544 |
2545 | # Analyze collected knowledge
2546 | # - All connected entities
2547 | # - Relation patterns
2548 | # - Knowledge clusters
2549 | ```
2550 |
2551 | ### Temporal Analysis
2552 |
2553 | **Track knowledge evolution over time**:
2554 |
2555 | ```python
2556 | # Get recent activity
2557 | week1 = await recent_activity(timeframe="7d", project="main")
2558 | week2 = await recent_activity(timeframe="14d", project="main")
2559 |
2560 | # Compare what's new
2561 | new_this_week = [
2562 | item for item in week1
2563 | if item not in week2
2564 | ]
2565 |
2566 | # Identify trends
2567 | # - What topics are active
2568 | # - What areas growing
2569 | # - What needs attention
2570 | ```
2571 |
2572 | ### Knowledge Validation
2573 |
2574 | **Ensure knowledge graph integrity**:
2575 |
2576 | ```python
2577 | # Find all forward references
2578 | all_notes = await search_notes(query="", page_size=1000, project="main")
2579 |
2580 | unresolved = []
2581 | for note in all_notes["results"]:
2582 | full_note = await read_note(note["permalink"], project="main")
2583 |
2584 | for relation in full_note["relations"]:
2585 | if not relation.get("target_exists"):
2586 | unresolved.append({
2587 | "source": note["title"],
2588 | "target": relation["target"]
2589 | })
2590 |
2591 | # Report unresolved references
2592 | # "Found {len(unresolved)} unresolved references:"
2593 | # - Note A -> Missing Target 1
2594 | # - Note B -> Missing Target 2
2595 | ```
2596 |
2597 | ### Automated Documentation
2598 |
2599 | **Generate documentation from knowledge graph**:
2600 |
2601 | ```python
2602 | # Gather all specs
2603 | specs = await search_notes(
2604 | query="",
2605 | types=["spec"],
2606 | project="main"
2607 | )
2608 |
2609 | # Build comprehensive documentation
2610 | doc_content = "# System Documentation\n\n"
2611 |
2612 | for spec in specs["results"]:
2613 | full_spec = await read_note(spec["permalink"], project="main")
2614 |
2615 | doc_content += f"\n## {full_spec['title']}\n"
2616 | doc_content += f"{full_spec['content']}\n"
2617 |
2618 | # Add related implementations
2619 | context = await build_context(
2620 | url=f"memory://{spec['permalink']}",
2621 | depth=1,
2622 | project="main"
2623 | )
2624 |
2625 | implementations = [
2626 | e for e in context["related_entities"]
2627 | if e.get("relation_type") == "implemented_by"
2628 | ]
2629 |
2630 | if implementations:
2631 | doc_content += "\n### Implementations\n"
2632 | for impl in implementations:
2633 | doc_content += f"- {impl['title']}\n"
2634 |
2635 | # Save generated documentation
2636 | await write_note(
2637 | title="Generated System Documentation",
2638 | content=doc_content,
2639 | folder="docs",
2640 | project="main"
2641 | )
2642 | ```
2643 |
2644 | ### Knowledge Consolidation
2645 |
2646 | **Merge related notes**:
2647 |
2648 | ```python
2649 | # Find related notes
2650 | related = await search_notes(
2651 | query="authentication",
2652 | project="main"
2653 | )
2654 |
2655 | # Read all related
2656 | notes_to_merge = []
2657 | for note in related["results"]:
2658 | full = await read_note(note["permalink"], project="main")
2659 | notes_to_merge.append(full)
2660 |
2661 | # Consolidate
2662 | merged_content = "# Consolidated: Authentication\n\n"
2663 |
2664 | merged_observations = []
2665 | merged_relations = []
2666 |
2667 | for note in notes_to_merge:
2668 | merged_observations.extend(note.get("observations", []))
2669 | merged_relations.extend(note.get("relations", []))
2670 |
2671 | # Deduplicate
2672 | unique_observations = list({
2673 | obs["content"]: obs for obs in merged_observations
2674 | }.values())
2675 |
2676 | unique_relations = list({
2677 | rel["target"]: rel for rel in merged_relations
2678 | }.values())
2679 |
2680 | # Build consolidated note
2681 | merged_content += "## Observations\n"
2682 | for obs in unique_observations:
2683 | merged_content += f"- [{obs['category']}] {obs['content']}"
2684 | if obs.get('tags'):
2685 | merged_content += " " + " ".join(f"#{tag}" for tag in obs['tags'])
2686 | merged_content += "\n"
2687 |
2688 | merged_content += "\n## Relations\n"
2689 | for rel in unique_relations:
2690 | merged_content += f"- {rel['type']} [[{rel['target']}]]\n"
2691 |
2692 | # Save consolidated note
2693 | await write_note(
2694 | title="Consolidated: Authentication",
2695 | content=merged_content,
2696 | folder="consolidated",
2697 | project="main"
2698 | )
2699 | ```
2700 |
2701 | ---
2702 |
2703 | ## Tool Reference
2704 |
2705 | **Complete reference for all MCP tools.**
2706 |
2707 | ### Content Management
2708 |
2709 | **write_note(title, content, folder, tags, entity_type, project)**
2710 | - Create or update markdown notes
2711 | - Parameters:
2712 | - `title` (required): Note title
2713 | - `content` (required): Markdown content
2714 | - `folder` (required): Destination folder
2715 | - `tags` (optional): List of tags
2716 | - `entity_type` (optional): Entity type (note, person, meeting, etc.)
2717 | - `project` (required unless default_project_mode): Target project
2718 | - Returns: Created/updated entity with permalink
2719 | - Example:
2720 | ```python
2721 | await write_note(
2722 | title="API Design",
2723 | content="# API Design\n...",
2724 | folder="specs",
2725 | tags=["api", "design"],
2726 | entity_type="spec",
2727 | project="main"
2728 | )
2729 | ```
2730 |
2731 | **read_note(identifier, page, page_size, project)**
2732 | - Read notes with knowledge graph context
2733 | - Parameters:
2734 | - `identifier` (required): Title, permalink, or memory:// URL
2735 | - `page` (optional): Page number (default: 1)
2736 | - `page_size` (optional): Results per page (default: 10)
2737 | - `project` (required unless default_project_mode): Target project
2738 | - Returns: Entity with content, observations, relations
2739 | - Example:
2740 | ```python
2741 | note = await read_note(
2742 | identifier="memory://specs/api-design",
2743 | project="main"
2744 | )
2745 | ```
2746 |
2747 | **edit_note(identifier, operation, content, find_text, section, expected_replacements, project)**
2748 | - Edit notes incrementally
2749 | - Parameters:
2750 | - `identifier` (required): Note identifier
2751 | - `operation` (required): append, prepend, find_replace, replace_section
2752 | - `content` (required): Content to add/replace
2753 | - `find_text` (optional): Text to find (for find_replace)
2754 | - `section` (optional): Section heading (for replace_section)
2755 | - `expected_replacements` (optional): Expected replacement count
2756 | - `project` (required unless default_project_mode): Target project
2757 | - Returns: Updated entity
2758 | - Example:
2759 | ```python
2760 | await edit_note(
2761 | identifier="API Design",
2762 | operation="append",
2763 | content="\n- [fact] New requirement",
2764 | project="main"
2765 | )
2766 | ```
2767 |
2768 | **move_note(identifier, destination_path, project)**
2769 | - Move notes to new locations
2770 | - Parameters:
2771 | - `identifier` (required): Note identifier
2772 | - `destination_path` (required): New path (with or without .md)
2773 | - `project` (required unless default_project_mode): Target project
2774 | - Returns: Updated entity with new path
2775 | - Example:
2776 | ```python
2777 | await move_note(
2778 | identifier="API Design",
2779 | destination_path="archive/api-design.md",
2780 | project="main"
2781 | )
2782 | ```
2783 |
2784 | **delete_note(identifier, project)**
2785 | - Delete notes from knowledge base
2786 | - Parameters:
2787 | - `identifier` (required): Note identifier
2788 | - `project` (required unless default_project_mode): Target project
2789 | - Returns: Deletion confirmation
2790 | - Example:
2791 | ```python
2792 | await delete_note(
2793 | identifier="outdated-note",
2794 | project="main"
2795 | )
2796 | ```
2797 |
2798 | **read_content(path, project)**
2799 | - Read raw file content
2800 | - Parameters:
2801 | - `path` (required): File path
2802 | - `project` (required unless default_project_mode): Target project
2803 | - Returns: Raw file content (text or base64 for binary)
2804 | - Example:
2805 | ```python
2806 | content = await read_content(
2807 | path="config/settings.json",
2808 | project="main"
2809 | )
2810 | ```
2811 |
2812 | **view_note(identifier, page, page_size, project)**
2813 | - View notes as formatted artifacts
2814 | - Parameters: Same as read_note
2815 | - Returns: Formatted markdown for display
2816 | - Example:
2817 | ```python
2818 | artifact = await view_note(
2819 | identifier="API Design",
2820 | project="main"
2821 | )
2822 | ```
2823 |
2824 | ### Knowledge Graph Navigation
2825 |
2826 | **build_context(url, depth, timeframe, max_related, page, page_size, project)**
2827 | - Navigate knowledge graph
2828 | - Parameters:
2829 | - `url` (required): memory:// URL
2830 | - `depth` (optional): Traversal depth (default: 1)
2831 | - `timeframe` (optional): Time window (e.g., "7d", "1 week")
2832 | - `max_related` (optional): Max related entities (default: 10)
2833 | - `page` (optional): Page number
2834 | - `page_size` (optional): Results per page
2835 | - `project` (required unless default_project_mode): Target project
2836 | - Returns: Root entity, related entities, paths
2837 | - Example:
2838 | ```python
2839 | context = await build_context(
2840 | url="memory://api-design",
2841 | depth=2,
2842 | timeframe="30d",
2843 | project="main"
2844 | )
2845 | ```
2846 |
2847 | **recent_activity(type, depth, timeframe, project)**
2848 | - Get recent changes
2849 | - Parameters:
2850 | - `type` (optional): Activity type filter
2851 | - `depth` (optional): Include related entities
2852 | - `timeframe` (optional): Time window (default: "7d")
2853 | - `project` (optional): Target project (omit for all projects)
2854 | - Returns: List of recently updated entities
2855 | - Example:
2856 | ```python
2857 | activity = await recent_activity(
2858 | timeframe="7d",
2859 | project="main"
2860 | )
2861 | ```
2862 |
2863 | **list_directory(dir_name, depth, file_name_glob, project)**
2864 | - Browse directory contents
2865 | - Parameters:
2866 | - `dir_name` (optional): Directory path (default: "/")
2867 | - `depth` (optional): Recursion depth (default: 1)
2868 | - `file_name_glob` (optional): File pattern (e.g., "*.md")
2869 | - `project` (required unless default_project_mode): Target project
2870 | - Returns: Files and subdirectories
2871 | - Example:
2872 | ```python
2873 | contents = await list_directory(
2874 | dir_name="specs",
2875 | depth=2,
2876 | file_name_glob="*.md",
2877 | project="main"
2878 | )
2879 | ```
2880 |
2881 | ### Search & Discovery
2882 |
2883 | **search_notes(query, page, page_size, search_type, types, entity_types, after_date, project)**
2884 | - Search across knowledge base
2885 | - Parameters:
2886 | - `query` (required): Search query
2887 | - `page` (optional): Page number (default: 1)
2888 | - `page_size` (optional): Results per page (default: 10)
2889 | - `search_type` (optional): "text" or "semantic"
2890 | - `types` (optional): Entity type filter
2891 | - `entity_types` (optional): Observation category filter
2892 | - `after_date` (optional): Date filter (ISO format)
2893 | - `project` (required unless default_project_mode): Target project
2894 | - Returns: Matching entities with scores
2895 | - Example:
2896 | ```python
2897 | results = await search_notes(
2898 | query="authentication",
2899 | types=["spec", "decision"],
2900 | after_date="2025-01-01",
2901 | project="main"
2902 | )
2903 | ```
2904 |
2905 | ### Project Management
2906 |
2907 | **list_memory_projects()**
2908 | - List all available projects
2909 | - Parameters: None
2910 | - Returns: List of projects with metadata
2911 | - Example:
2912 | ```python
2913 | projects = await list_memory_projects()
2914 | ```
2915 |
2916 | **create_memory_project(project_name, project_path, set_default)**
2917 | - Create new project
2918 | - Parameters:
2919 | - `project_name` (required): Project name
2920 | - `project_path` (required): Directory path
2921 | - `set_default` (optional): Set as default (default: False)
2922 | - Returns: Created project details
2923 | - Example:
2924 | ```python
2925 | await create_memory_project(
2926 | project_name="research",
2927 | project_path="/Users/name/research",
2928 | set_default=False
2929 | )
2930 | ```
2931 |
2932 | **delete_project(project_name)**
2933 | - Delete project from configuration
2934 | - Parameters:
2935 | - `project_name` (required): Project to delete
2936 | - Returns: Deletion confirmation
2937 | - Example:
2938 | ```python
2939 | await delete_project(project_name="old-project")
2940 | ```
2941 |
2942 | **sync_status(project)**
2943 | - Check synchronization status
2944 | - Parameters:
2945 | - `project` (optional): Target project
2946 | - Returns: Sync progress and status
2947 | - Example:
2948 | ```python
2949 | status = await sync_status(project="main")
2950 | ```
2951 |
2952 | ### Visualization
2953 |
2954 | **canvas(nodes, edges, title, folder, project)**
2955 | - Create Obsidian canvas
2956 | - Parameters:
2957 | - `nodes` (required): List of node objects
2958 | - `edges` (required): List of edge objects
2959 | - `title` (required): Canvas title
2960 | - `folder` (required): Destination folder
2961 | - `project` (required unless default_project_mode): Target project
2962 | - Returns: Created canvas file
2963 | - Example:
2964 | ```python
2965 | await canvas(
2966 | nodes=[{"id": "1", "type": "file", "file": "note.md", "x": 0, "y": 0}],
2967 | edges=[],
2968 | title="Graph View",
2969 | folder="diagrams",
2970 | project="main"
2971 | )
2972 | ```
2973 |
2974 | ---
2975 |
2976 | ## Best Practices
2977 |
2978 | **Guidelines for effective knowledge management and AI collaboration.**
2979 |
2980 | ### 1. Project Setup
2981 |
2982 | **Single-project users**:
2983 | - Enable `default_project_mode=true` in config
2984 | - Simplifies tool calls
2985 | - Less explicit project parameters
2986 |
2987 | **Multi-project users**:
2988 | - Keep `default_project_mode=false`
2989 | - Always specify project explicitly
2990 | - Prevents cross-project errors
2991 |
2992 | **Always start with discovery**:
2993 | ```python
2994 | # First action in conversation
2995 | projects = await list_memory_projects()
2996 |
2997 | # Ask user which to use
2998 | # Store for session
2999 | # Use consistently
3000 | ```
3001 |
3002 | ### 2. Knowledge Structure
3003 |
3004 | **Every note should have**:
3005 | - Clear, descriptive title
3006 | - 3-5 observations minimum
3007 | - 2-3 relations minimum
3008 | - Appropriate categories and tags
3009 | - Proper frontmatter
3010 |
3011 | **Good structure example**:
3012 | ```markdown
3013 | ---
3014 | title: Clear Descriptive Title
3015 | tags: [relevant, tags, here]
3016 | type: note
3017 | ---
3018 |
3019 | # Title
3020 |
3021 | ## Context
3022 | Brief background
3023 |
3024 | ## Observations
3025 | - [category] Specific fact #tag1 #tag2
3026 | - [category] Another fact #tag3
3027 | - [category] Third fact #tag4
3028 |
3029 | ## Relations
3030 | - relation_type [[Related Entity 1]]
3031 | - relation_type [[Related Entity 2]]
3032 | ```
3033 |
3034 | ### 3. Search Before Creating
3035 |
3036 | **Always search first**:
3037 | ```python
3038 | # Before writing new note
3039 | existing = await search_notes(
3040 | query="topic name",
3041 | project="main"
3042 | )
3043 |
3044 | if existing["total"] > 0:
3045 | # Update existing instead of creating duplicate
3046 | await edit_note(
3047 | identifier=existing["results"][0]["permalink"],
3048 | operation="append",
3049 | content=new_information,
3050 | project="main"
3051 | )
3052 | else:
3053 | # Create new
3054 | await write_note(...)
3055 | ```
3056 |
3057 | ### 4. Use Exact Entity Titles in Relations
3058 |
3059 | **Wrong**:
3060 | ```markdown
3061 | ## Relations
3062 | - relates_to [[auth system]] # Won't match "Authentication System"
3063 | - implements [[api spec]] # Won't match "API Specification"
3064 | ```
3065 |
3066 | **Right**:
3067 | ```python
3068 | # Search for exact title
3069 | results = await search_notes(query="Authentication System", project="main")
3070 | exact_title = results["results"][0]["title"]
3071 |
3072 | # Use in relation
3073 | content = f"## Relations\n- relates_to [[{exact_title}]]"
3074 | ```
3075 |
3076 | ### 5. Meaningful Categories
3077 |
3078 | **Use semantic categories**:
3079 | - `[decision]` for choices made
3080 | - `[fact]` for objective information
3081 | - `[technique]` for methods
3082 | - `[requirement]` for needs
3083 | - `[insight]` for realizations
3084 | - `[problem]` for issues
3085 | - `[solution]` for resolutions
3086 | - `[action]` for tasks
3087 |
3088 | **Not generic categories**:
3089 | - Avoid `[note]`, `[info]`, `[misc]`
3090 | - Be specific and intentional
3091 |
3092 | ### 6. Descriptive Relation Types
3093 |
3094 | **Use meaningful relation types**:
3095 | - `implements` for implementation
3096 | - `requires` for dependencies
3097 | - `part_of` for hierarchy
3098 | - `extends` for enhancement
3099 | - `contrasts_with` for alternatives
3100 |
3101 | **Not generic**:
3102 | - Avoid overusing `relates_to`
3103 | - Be specific about relationship
3104 |
3105 | ### 7. Progressive Elaboration
3106 |
3107 | **Build knowledge over time**:
3108 | ```python
3109 | # Session 1: Create foundation
3110 | await write_note(
3111 | title="Topic",
3112 | content="Basic structure with initial observations",
3113 | folder="notes",
3114 | project="main"
3115 | )
3116 |
3117 | # Session 2: Add details
3118 | await edit_note(
3119 | identifier="Topic",
3120 | operation="append",
3121 | content="Additional observations and insights",
3122 | project="main"
3123 | )
3124 |
3125 | # Session 3: Add relations
3126 | await edit_note(
3127 | identifier="Topic",
3128 | operation="append",
3129 | content="Relations to related topics",
3130 | project="main"
3131 | )
3132 | ```
3133 |
3134 | ### 8. Consistent Naming
3135 |
3136 | **Folder structure**:
3137 | - specs/ - Specifications
3138 | - decisions/ - Decision records
3139 | - meetings/ - Meeting notes
3140 | - conversations/ - AI conversations
3141 | - implementations/ - Code/implementations
3142 | - docs/ - Documentation
3143 |
3144 | **File naming**:
3145 | - Use descriptive titles
3146 | - Consistent format
3147 | - Avoid special characters
3148 |
3149 | ### 9. Regular Validation
3150 |
3151 | **Check knowledge graph health**:
3152 | ```python
3153 | # Find unresolved references
3154 | # Check for orphaned notes
3155 | # Verify relation consistency
3156 | # Update outdated information
3157 | ```
3158 |
3159 | ### 10. Permission and Transparency
3160 |
3161 | **With users**:
3162 | - Always ask before recording
3163 | - Confirm after saving
3164 | - Explain what was saved
3165 | - Describe how it helps
3166 |
3167 | **Recording pattern**:
3168 | ```
3169 | AI: "Would you like me to save our discussion about {topic}?"
3170 | User: "Yes"
3171 | AI: [Saves to Basic Memory]
3172 | "Saved as '{title}' in {folder}/"
3173 | ```
3174 |
3175 | ### 11. Context Building Strategy
3176 |
3177 | **For new conversations**:
3178 | ```python
3179 | # 1. Search for topic
3180 | results = await search_notes(query="topic", project="main")
3181 |
3182 | # 2. Build context from top result
3183 | context = await build_context(
3184 | url=f"memory://{results['results'][0]['permalink']}",
3185 | depth=2,
3186 | timeframe="30d",
3187 | project="main"
3188 | )
3189 |
3190 | # 3. Use context to inform response
3191 | # Reference previous knowledge
3192 | # Build on existing understanding
3193 | ```
3194 |
3195 | ### 12. Error Recovery
3196 |
3197 | **Graceful degradation**:
3198 | ```python
3199 | try:
3200 | # Attempt operation
3201 | result = await tool_call(...)
3202 | except:
3203 | # Fall back to alternative
3204 | # Inform user of issue
3205 | # Suggest workaround
3206 | ```
3207 |
3208 | ### 13. Incremental Updates
3209 |
3210 | **Prefer editing over rewriting**:
3211 | ```python
3212 | # Good: Incremental update
3213 | await edit_note(
3214 | identifier="Note",
3215 | operation="append",
3216 | content="New information",
3217 | project="main"
3218 | )
3219 |
3220 | # Avoid: Complete rewrite
3221 | # (unless necessary for major restructuring)
3222 | ```
3223 |
3224 | ### 14. Tagging Strategy
3225 |
3226 | **Use tags strategically**:
3227 | - Technology: #python #fastapi
3228 | - Domain: #auth #security
3229 | - Status: #wip #completed
3230 | - Priority: #urgent #important
3231 | - Category: #bug #feature
3232 |
3233 | **Not too many**:
3234 | - 3-5 tags per observation
3235 | - Focus on most relevant
3236 | - Avoid tag proliferation
3237 |
3238 | ### 15. Documentation as Code
3239 |
3240 | **Treat knowledge like code**:
3241 | - Version control friendly (markdown)
3242 | - Review and refine regularly
3243 | - Keep it DRY (Don't Repeat Yourself)
3244 | - Link instead of duplicating
3245 | - Maintain consistency
3246 |
3247 | ---
3248 |
3249 | ## Conclusion
3250 |
3251 | This extended guide provides comprehensive coverage of Basic Memory's capabilities for AI assistants. Each section is designed to be self-contained so you can reference or copy specific sections as needed.
3252 |
3253 | For the condensed quick-reference version, see the [AI Assistant Guide](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/resources/ai_assistant_guide.md).
3254 |
3255 | For complete documentation including setup, integrations, and advanced features, visit [docs.basicmemory.com](https://docs.basicmemory.com).
3256 |
3257 | **Remember**: Basic Memory is about building persistent, structured knowledge that grows over time. Focus on creating rich observations, meaningful relations, and building a connected knowledge graph that provides lasting value across conversations and sessions.
3258 |
3259 | Built with ♥️ by Basic Machines
3260 |
```