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