basic-memory 0.15.0__py3-none-any.whl → 0.15.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of basic-memory might be problematic. Click here for more details.

Files changed (47) hide show
  1. basic_memory/__init__.py +1 -1
  2. basic_memory/api/routers/directory_router.py +23 -2
  3. basic_memory/api/routers/project_router.py +1 -0
  4. basic_memory/cli/auth.py +2 -2
  5. basic_memory/cli/commands/command_utils.py +11 -28
  6. basic_memory/cli/commands/mcp.py +72 -67
  7. basic_memory/cli/commands/project.py +54 -49
  8. basic_memory/cli/commands/status.py +6 -15
  9. basic_memory/config.py +55 -9
  10. basic_memory/deps.py +7 -5
  11. basic_memory/ignore_utils.py +7 -7
  12. basic_memory/mcp/async_client.py +102 -4
  13. basic_memory/mcp/prompts/continue_conversation.py +16 -15
  14. basic_memory/mcp/prompts/search.py +12 -11
  15. basic_memory/mcp/resources/ai_assistant_guide.md +185 -453
  16. basic_memory/mcp/resources/project_info.py +9 -7
  17. basic_memory/mcp/tools/build_context.py +40 -39
  18. basic_memory/mcp/tools/canvas.py +21 -20
  19. basic_memory/mcp/tools/chatgpt_tools.py +11 -2
  20. basic_memory/mcp/tools/delete_note.py +22 -21
  21. basic_memory/mcp/tools/edit_note.py +105 -104
  22. basic_memory/mcp/tools/list_directory.py +98 -95
  23. basic_memory/mcp/tools/move_note.py +127 -125
  24. basic_memory/mcp/tools/project_management.py +101 -98
  25. basic_memory/mcp/tools/read_content.py +64 -63
  26. basic_memory/mcp/tools/read_note.py +88 -88
  27. basic_memory/mcp/tools/recent_activity.py +139 -135
  28. basic_memory/mcp/tools/search.py +27 -26
  29. basic_memory/mcp/tools/sync_status.py +133 -128
  30. basic_memory/mcp/tools/utils.py +0 -15
  31. basic_memory/mcp/tools/view_note.py +14 -28
  32. basic_memory/mcp/tools/write_note.py +97 -87
  33. basic_memory/repository/entity_repository.py +60 -0
  34. basic_memory/repository/repository.py +16 -3
  35. basic_memory/repository/search_repository.py +42 -0
  36. basic_memory/schemas/project_info.py +1 -1
  37. basic_memory/services/directory_service.py +124 -3
  38. basic_memory/services/entity_service.py +31 -9
  39. basic_memory/services/project_service.py +97 -10
  40. basic_memory/services/search_service.py +16 -8
  41. basic_memory/sync/sync_service.py +28 -13
  42. {basic_memory-0.15.0.dist-info → basic_memory-0.15.1.dist-info}/METADATA +51 -4
  43. {basic_memory-0.15.0.dist-info → basic_memory-0.15.1.dist-info}/RECORD +46 -47
  44. basic_memory/mcp/tools/headers.py +0 -44
  45. {basic_memory-0.15.0.dist-info → basic_memory-0.15.1.dist-info}/WHEEL +0 -0
  46. {basic_memory-0.15.0.dist-info → basic_memory-0.15.1.dist-info}/entry_points.txt +0 -0
  47. {basic_memory-0.15.0.dist-info → basic_memory-0.15.1.dist-info}/licenses/LICENSE +0 -0
@@ -1,551 +1,283 @@
1
1
  # AI Assistant Guide for Basic Memory
2
2
 
3
- This guide helps AIs use Basic Memory tools effectively when working with users. It covers reading, writing, and
4
- navigating knowledge through the Model Context Protocol (MCP).
3
+ Quick reference for using Basic Memory tools effectively through MCP.
5
4
 
6
- ## Overview
5
+ **For comprehensive coverage**: See the [Extended AI Assistant Guide](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ai-assistant-guide-extended.md) with detailed examples, advanced patterns, and self-contained sections.
7
6
 
8
- Basic Memory allows you and users to record context in local Markdown files, building a rich knowledge base through
9
- natural conversations. The system automatically creates a semantic knowledge graph from simple text patterns.
7
+ ## Overview
10
8
 
11
- - **Local-First**: All data is stored in plain text files on the user's computer
12
- - **Real-Time**: Users see content updates immediately
13
- - **Bi-Directional**: Both you and users can read and edit notes
14
- - **Semantic**: Simple patterns create a structured knowledge graph
15
- - **Persistent**: Knowledge persists across sessions and conversations
9
+ Basic Memory creates a semantic knowledge graph from markdown files. Focus on building rich connections between notes.
16
10
 
17
- ## Project Management and Configuration
11
+ - **Local-First**: Plain text files on user's computer
12
+ - **Persistent**: Knowledge survives across sessions
13
+ - **Semantic**: Observations and relations create a knowledge graph
18
14
 
19
- Basic Memory uses a **stateless architecture** where each tool call can specify which project to work with. This provides three ways to determine the active project:
15
+ **Your role**: You're helping humans build enduring knowledge they'll own forever. The semantic graph (observations, relations, context) helps you provide better assistance by understanding connections and maintaining continuity. Think: lasting insights worth keeping, not disposable chat logs.
20
16
 
21
- ### Three-Tier Project Resolution
17
+ ## Project Management
22
18
 
23
- 1. **CLI Constraint (Highest Priority)**: When Basic Memory is started with `--project project-name`, all operations are constrained to that project
24
- 2. **Explicit Project Parameter (Medium Priority)**: When you specify `project="project-name"` in tool calls
25
- 3. **Default Project Mode (Lowest Priority)**: When `default_project_mode=true` in configuration, tools automatically use the configured `default_project`
19
+ All tools require explicit project specification.
26
20
 
27
- ### Default Project Mode
21
+ **Three-tier resolution:**
22
+ 1. CLI constraint: `--project name` (highest priority)
23
+ 2. Explicit parameter: `project="name"` in tool calls
24
+ 3. Default mode: `default_project_mode=true` in config (fallback)
28
25
 
29
- When `default_project_mode` is enabled in the user's configuration:
30
- - All tools become more convenient - no need to specify project repeatedly
31
- - Perfect for users who primarily work with a single project
32
- - Still allows explicit project specification when needed
33
- - Falls back gracefully to multi-project mode if no default is configured
26
+ ### Quick Setup Check
34
27
 
35
28
  ```python
36
- # With default_project_mode enabled, these are equivalent:
37
- await write_note("My Note", "Content", "folder")
38
- await write_note("My Note", "Content", "folder", project="default-project")
29
+ # Discover projects
30
+ projects = await list_memory_projects()
39
31
 
40
- # You can still override with explicit project:
41
- await write_note("My Note", "Content", "folder", project="other-project")
32
+ # Check if default_project_mode enabled
33
+ # If yes: project parameter optional
34
+ # If no: project parameter required
42
35
  ```
43
36
 
44
- ### Project Discovery
37
+ ### Default Project Mode
45
38
 
46
- If you're unsure which project to use:
39
+ When `default_project_mode=true`:
47
40
  ```python
48
- # Discover available projects
49
- projects = await list_memory_projects()
50
-
51
- # See recent activity across projects for recommendations
52
- activity = await recent_activity() # Shows cross-project activity and suggestions
41
+ # These are equivalent:
42
+ await write_note("Note", "Content", "folder")
43
+ await write_note("Note", "Content", "folder", project="main")
53
44
  ```
54
45
 
55
- ## The Importance of the Knowledge Graph
56
-
57
- **Basic Memory's value comes from connections between notes, not just the notes themselves.**
58
-
59
- When writing notes, your primary goal should be creating a rich, interconnected knowledge graph:
60
-
61
- 1. **Increase Semantic Density**: Add multiple observations and relations to each note
62
- 2. **Use Accurate References**: Aim to reference existing entities by their exact titles
63
- 3. **Create Forward References**: Feel free to reference entities that don't exist yet - Basic Memory will resolve these
64
- when they're created later
65
- 4. **Create Bidirectional Links**: When appropriate, connect entities from both directions
66
- 5. **Use Meaningful Categories**: Add semantic context with appropriate observation categories
67
- 6. **Choose Precise Relations**: Use specific relation types that convey meaning
68
-
69
- Remember: A knowledge graph with 10 heavily connected notes is more valuable than 20 isolated notes. Your job is to help
70
- build these connections!
71
-
72
- ## Core Tools Reference
73
-
74
- ### Knowledge Creation and Editing
75
-
46
+ When `default_project_mode=false` (default):
76
47
  ```python
77
- # Writing knowledge - THE MOST IMPORTANT TOOL!
78
- response = await write_note(
79
- title="Search Design", # Required: Note title
80
- content="# Search Design\n...", # Required: Note content
81
- folder="specs", # Required: Folder to save in
82
- tags=["search", "design"], # Optional: Tags for categorization
83
- project="my-project" # Optional: Explicit project (uses default if not specified)
84
- )
48
+ # Project required:
49
+ await write_note("Note", "Content", "folder", project="main") # ✓
50
+ await write_note("Note", "Content", "folder") # Error
51
+ ```
85
52
 
86
- # Editing existing notes
87
- await edit_note(
88
- identifier="Search Design", # Required: Note to edit
89
- operation="append", # Required: append, prepend, find_replace, replace_section
90
- content="\n## New Section\nAdditional content", # Required: Content to add/replace
91
- project="my-project" # Optional: Explicit project
92
- )
53
+ ## Core Tools
93
54
 
94
- # Moving notes
95
- await move_note(
96
- identifier="Search Design", # Required: Note to move
97
- destination_path="archive/old-search-design.md", # Required: New location
98
- project="my-project" # Optional: Explicit project
99
- )
55
+ ### Writing Knowledge
100
56
 
101
- # Deleting notes
102
- success = await delete_note(
103
- identifier="Old Draft", # Required: Note to delete
104
- project="my-project" # Optional: Explicit project
57
+ ```python
58
+ await write_note(
59
+ title="Topic",
60
+ content="# Topic\n## Observations\n- [category] fact\n## Relations\n- relates_to [[Other]]",
61
+ folder="notes",
62
+ project="main" # Required unless default_project_mode=true
105
63
  )
106
64
  ```
107
65
 
108
- ### Knowledge Reading and Discovery
66
+ ### Reading Knowledge
109
67
 
110
68
  ```python
111
- # Reading knowledge
112
- content = await read_note("Search Design") # By title (uses default project)
113
- content = await read_note("specs/search-design") # By path
114
- content = await read_note("memory://specs/search") # By memory URL
115
- content = await read_note("Search Design", project="work-docs") # Explicit project
116
-
117
- # Reading raw file content (text, images, binaries)
118
- file_data = await read_content(
119
- path="assets/diagram.png", # Required: File path
120
- project="my-project" # Optional: Explicit project
121
- )
122
-
123
- # Viewing notes as formatted artifacts
124
- await view_note(
125
- identifier="Search Design", # Required: Note to view
126
- project="my-project", # Optional: Explicit project
127
- page=1, # Optional: Pagination
128
- page_size=10 # Optional: Items per page
129
- )
69
+ # By identifier
70
+ content = await read_note("Topic", project="main")
130
71
 
131
- # Browsing directory contents
132
- listing = await list_directory(
133
- dir_name="/specs", # Optional: Directory path (default: "/")
134
- depth=2, # Optional: Recursion depth
135
- file_name_glob="*.md", # Optional: File pattern filter
136
- project="my-project" # Optional: Explicit project
137
- )
72
+ # By memory:// URL
73
+ content = await read_note("memory://folder/topic", project="main")
138
74
  ```
139
75
 
140
- ### Search and Context
76
+ ### Searching
141
77
 
142
78
  ```python
143
- # Searching for knowledge
144
79
  results = await search_notes(
145
- query="authentication system", # Required: Text to search for
146
- project="my-project", # Optional: Explicit project
147
- page=1, # Optional: Pagination
148
- page_size=10, # Optional: Results per page
149
- search_type="text", # Optional: "text", "title", or "permalink"
150
- types=["entity"], # Optional: Filter by content types
151
- entity_types=["observation"], # Optional: Filter by entity types
152
- after_date="1 week" # Optional: Recent content only
153
- )
154
-
155
- # Building context from the knowledge graph
156
- context = await build_context(
157
- url="memory://specs/search", # Required: Starting point
158
- project="my-project", # Optional: Explicit project
159
- depth=2, # Optional: How many hops to follow
160
- timeframe="1 month", # Optional: Recent timeframe
161
- max_related=10 # Optional: Max related items
162
- )
163
-
164
- # Checking recent changes
165
- activity = await recent_activity(
166
- type=["entity", "relation"], # Optional: Entity types to include
167
- depth=1, # Optional: Related items to include
168
- timeframe="1 week", # Optional: Time window
169
- project="my-project" # Optional: Explicit project (None for cross-project discovery)
80
+ query="authentication",
81
+ project="main",
82
+ page_size=10
170
83
  )
171
84
  ```
172
85
 
173
- ### Visualization and Project Management
86
+ ### Building Context
174
87
 
175
88
  ```python
176
- # Creating a knowledge visualization
177
- canvas_result = await canvas(
178
- nodes=[{"id": "note1", "type": "file", "file": "Search Design.md"}], # Required: Nodes
179
- edges=[{"id": "edge1", "fromNode": "note1", "toNode": "note2"}], # Required: Edges
180
- title="Project Overview", # Required: Canvas title
181
- folder="diagrams", # Required: Storage location
182
- project="my-project" # Optional: Explicit project
89
+ context = await build_context(
90
+ url="memory://specs/auth",
91
+ project="main",
92
+ depth=2,
93
+ timeframe="1 week"
183
94
  )
184
-
185
- # Project management
186
- projects = await list_memory_projects() # List all available projects
187
- project_info = await project_info(project="my-project") # Get project statistics
188
95
  ```
189
96
 
190
- ## memory:// URLs Explained
191
-
192
- Basic Memory uses a special URL format to reference entities in the knowledge graph:
193
-
194
- - `memory://title` - Reference by title
195
- - `memory://folder/title` - Reference by folder and title
196
- - `memory://permalink` - Reference by permalink
197
- - `memory://path/relation_type/*` - Follow all relations of a specific type
198
- - `memory://path/*/target` - Find all entities with relations to target
97
+ ## Knowledge Graph Essentials
199
98
 
200
- ## Semantic Markdown Format
201
-
202
- Knowledge is encoded in standard markdown using simple patterns:
203
-
204
- **Observations** - Facts about an entity:
99
+ ### Observations
205
100
 
101
+ Categorized facts with optional tags:
206
102
  ```markdown
207
- - [category] This is an observation #tag1 #tag2 (optional context)
103
+ - [decision] Use JWT for authentication #security
104
+ - [technique] Hash passwords with bcrypt #best-practice
105
+ - [requirement] Support OAuth 2.0 providers
208
106
  ```
209
107
 
210
- **Relations** - Links between entities:
108
+ ### Relations
211
109
 
110
+ Directional links between entities:
212
111
  ```markdown
213
- - relation_type [[Target Entity]] (optional context)
112
+ - implements [[Authentication Spec]]
113
+ - requires [[User Database]]
114
+ - extends [[Base Security Model]]
214
115
  ```
215
116
 
216
- **Common Categories & Relation Types:**
217
-
218
- - Categories: `[idea]`, `[decision]`, `[question]`, `[fact]`, `[requirement]`, `[technique]`, `[recipe]`, `[preference]`
219
- - Relations: `relates_to`, `implements`, `requires`, `extends`, `part_of`, `pairs_with`, `inspired_by`,
220
- `originated_from`
221
-
222
- ## When to Record Context
223
-
224
- **Always consider recording context when**:
225
-
226
- 1. Users make decisions or reach conclusions
227
- 2. Important information emerges during conversation
228
- 3. Multiple related topics are discussed
229
- 4. The conversation contains information that might be useful later
230
- 5. Plans, tasks, or action items are mentioned
117
+ **Common relation types:** `relates_to`, `implements`, `requires`, `extends`, `part_of`, `contrasts_with`
231
118
 
232
- **Protocol for recording context**:
119
+ ### Forward References
233
120
 
234
- 1. Identify valuable information in the conversation
235
- 2. Ask the user: "Would you like me to record our discussion about [topic] in Basic Memory?"
236
- 3. If they agree, use `write_note` to capture the information
237
- 4. If they decline, continue without recording
238
- 5. Let the user know when information has been recorded: "I've saved our discussion about [topic] to Basic Memory."
239
-
240
- ## Understanding User Interactions
241
-
242
- Users will interact with Basic Memory in patterns like:
121
+ Reference entities that don't exist yet:
122
+ ```python
123
+ # Create note with forward reference
124
+ await write_note(
125
+ title="Login Flow",
126
+ content="## Relations\n- requires [[OAuth Provider]]", # Doesn't exist yet
127
+ folder="auth",
128
+ project="main"
129
+ )
243
130
 
244
- 1. **Creating knowledge**:
245
- ```
246
- Human: "Let's write up what we discussed about search."
131
+ # Later, create referenced entity
132
+ await write_note(
133
+ title="OAuth Provider",
134
+ content="# OAuth Provider\n...",
135
+ folder="auth",
136
+ project="main"
137
+ )
138
+ # → Relation automatically resolved
139
+ ```
247
140
 
248
- You: I'll create a note capturing our discussion about the search functionality.
249
- await write_note(
250
- title="Search Functionality Discussion",
251
- content="# Search Functionality Discussion\n...",
252
- folder="discussions"
253
- )
254
- ```
141
+ ## Best Practices
255
142
 
256
- 2. **Referencing existing knowledge**:
257
- ```
258
- Human: "Take a look at memory://specs/search"
143
+ ### 1. Project Management
259
144
 
260
- You: I'll examine that information.
261
- context = await build_context(url="memory://specs/search")
262
- content = await read_note("specs/search")
263
- ```
145
+ **Single-project users:**
146
+ - Enable `default_project_mode=true`
147
+ - Simpler tool calls
264
148
 
265
- 3. **Finding information**:
266
- ```
267
- Human: "What were our decisions about auth?"
149
+ **Multi-project users:**
150
+ - Keep `default_project_mode=false`
151
+ - Always specify project explicitly
268
152
 
269
- You: Let me find that information for you.
270
- results = await search_notes(query="auth decisions")
271
- context = await build_context(url=f"memory://{results[0].permalink}")
272
- ```
153
+ **Discovery:**
154
+ ```python
155
+ # Start with discovery
156
+ projects = await list_memory_projects()
273
157
 
274
- ## Key Things to Remember
158
+ # Cross-project activity (no project param = all projects)
159
+ activity = await recent_activity()
275
160
 
276
- 1. **Files are Truth**
277
- - All knowledge lives in local files on the user's computer
278
- - Users can edit files outside your interaction
279
- - Changes need to be synced by the user (usually automatic)
280
- - Always verify information is current with `recent_activity()`
161
+ # Or specific project
162
+ activity = await recent_activity(project="main")
163
+ ```
281
164
 
282
- 2. **Building Context Effectively**
283
- - Start with specific entities
284
- - Follow meaningful relations
285
- - Check recent changes
286
- - Build context incrementally
287
- - Combine related information
165
+ ### 2. Building Rich Graphs
288
166
 
289
- 3. **Writing Knowledge Wisely**
290
- - Using the same title+folder will overwrite existing notes
291
- - Structure content with clear headings and sections
292
- - Use semantic markup for observations and relations
293
- - Keep files organized in logical folders
167
+ **Always include:**
168
+ - 3-5 observations per note
169
+ - 2-3 relations per note
170
+ - Meaningful categories and relation types
294
171
 
295
- ## Common Knowledge Patterns
172
+ **Search before creating:**
173
+ ```python
174
+ # Find existing entities to reference
175
+ results = await search_notes(query="authentication", project="main")
176
+ # Use exact titles in [[WikiLinks]]
177
+ ```
296
178
 
297
- ### Capturing Decisions
179
+ ### 3. Writing Effective Notes
298
180
 
181
+ **Structure:**
299
182
  ```markdown
300
- # Coffee Brewing Methods
183
+ # Title
301
184
 
302
185
  ## Context
303
-
304
- I've experimented with various brewing methods including French press, pour over, and espresso.
305
-
306
- ## Decision
307
-
308
- Pour over is my preferred method for light to medium roasts because it highlights subtle flavors and offers more control
309
- over the extraction.
186
+ Background information
310
187
 
311
188
  ## Observations
312
-
313
- - [technique] Blooming the coffee grounds for 30 seconds improves extraction #brewing
314
- - [preference] Water temperature between 195-205°F works best #temperature
315
- - [equipment] Gooseneck kettle provides better control of water flow #tools
189
+ - [category] Fact with #tags
190
+ - [category] Another fact
316
191
 
317
192
  ## Relations
318
-
319
- - pairs_with [[Light Roast Beans]]
320
- - contrasts_with [[French Press Method]]
321
- - requires [[Proper Grinding Technique]]
193
+ - relation_type [[Exact Entity Title]]
322
194
  ```
323
195
 
324
- ### Recording Project Structure
325
-
326
- ```markdown
327
- # Garden Planning
328
-
329
- ## Overview
196
+ **Categories:** `[idea]`, `[decision]`, `[fact]`, `[technique]`, `[requirement]`
330
197
 
331
- This document outlines the garden layout and planting strategy for this season.
198
+ ### 4. Error Handling
332
199
 
333
- ## Observations
334
-
335
- - [structure] Raised beds in south corner for sun exposure #layout
336
- - [structure] Drip irrigation system installed for efficiency #watering
337
- - [pattern] Companion planting used to deter pests naturally #technique
338
-
339
- ## Relations
340
-
341
- - contains [[Vegetable Section]]
342
- - contains [[Herb Garden]]
343
- - implements [[Organic Gardening Principles]]
200
+ **Missing project:**
201
+ ```python
202
+ try:
203
+ await search_notes(query="test") # Missing project parameter - will error
204
+ except:
205
+ # Show available projects
206
+ projects = await list_memory_projects()
207
+ # Then retry with project
208
+ results = await search_notes(query="test", project=projects[0].name)
344
209
  ```
345
210
 
346
- ### Technical Discussions
211
+ **Forward references:**
212
+ ```python
213
+ # Check response for unresolved relations
214
+ response = await write_note(
215
+ title="New Topic",
216
+ content="## Relations\n- relates_to [[Future Topic]]",
217
+ folder="notes",
218
+ project="main"
219
+ )
220
+ # Forward refs will resolve when target created
221
+ ```
347
222
 
348
- ```markdown
349
- # Recipe Improvement Discussion
223
+ ### 5. Recording Context
350
224
 
351
- ## Key Points
225
+ **Ask permission:**
226
+ > "Would you like me to save our discussion about [topic] to Basic Memory?"
352
227
 
353
- Discussed strategies for improving the chocolate chip cookie recipe.
228
+ **Confirm when done:**
229
+ > "I've saved our discussion to Basic Memory."
354
230
 
355
- ## Observations
231
+ **What to record:**
232
+ - Decisions and rationales
233
+ - Important discoveries
234
+ - Action items and plans
235
+ - Connected topics
356
236
 
357
- - [issue] Cookies spread too thin when baked at 350°F #texture
358
- - [solution] Chilling dough for 24 hours improves flavor and reduces spreading #technique
359
- - [decision] Will use brown butter instead of regular butter #flavor
237
+ ## Common Patterns
360
238
 
361
- ## Relations
239
+ ### Capture Decision
362
240
 
363
- - improves [[Basic Cookie Recipe]]
364
- - inspired_by [[Bakery-Style Cookies]]
365
- - pairs_with [[Homemade Ice Cream]]
241
+ ```python
242
+ await write_note(
243
+ title="DB Choice",
244
+ content="""# DB Choice\n## Decision\nUse PostgreSQL\n## Observations\n- [requirement] ACID compliance #reliability\n- [decision] PostgreSQL over MySQL\n## Relations\n- implements [[Data Architecture]]""",
245
+ folder="decisions",
246
+ project="main"
247
+ )
366
248
  ```
367
249
 
368
- ### Creating Effective Relations
369
-
370
- When creating relations, you can:
371
-
372
- 1. Reference existing entities by their exact title
373
- 2. Create forward references to entities that don't exist yet
250
+ ### Link Topics & Build Context
374
251
 
375
252
  ```python
376
- # Example workflow for creating notes with effective relations
377
- async def create_note_with_effective_relations():
378
- # Search for existing entities to reference
379
- search_results = await search_notes(query="travel")
380
- existing_entities = [result.title for result in search_results.primary_results]
253
+ # Link bidirectionally
254
+ await write_note(title="API Auth", content="## Relations\n- part_of [[API Design]]", folder="api", project="main")
255
+ await edit_note(identifier="API Design", operation="append", content="\n- includes [[API Auth]]", project="main")
381
256
 
382
- # Check if specific entities exist
383
- packing_tips_exists = "Packing Tips" in existing_entities
384
- japan_travel_exists = "Japan Travel Guide" in existing_entities
385
-
386
- # Prepare relations section - include both existing and forward references
387
- relations_section = "## Relations\n"
388
-
389
- # Existing reference - exact match to known entity
390
- if packing_tips_exists:
391
- relations_section += "- references [[Packing Tips]]\n"
392
- else:
393
- # Forward reference - will be linked when that entity is created later
394
- relations_section += "- references [[Packing Tips]]\n"
395
-
396
- # Another possible reference
397
- if japan_travel_exists:
398
- relations_section += "- part_of [[Japan Travel Guide]]\n"
399
-
400
- # You can also check recently modified notes to reference them
401
- recent = await recent_activity(timeframe="1 week")
402
- recent_titles = [item.title for item in recent.primary_results]
403
-
404
- if "Transportation Options" in recent_titles:
405
- relations_section += "- relates_to [[Transportation Options]]\n"
406
-
407
- # Always include meaningful forward references, even if they don't exist yet
408
- relations_section += "- located_in [[Tokyo]]\n"
409
- relations_section += "- visited_during [[Spring 2023 Trip]]\n"
257
+ # Search and build context
258
+ results = await search_notes(query="authentication", project="main")
259
+ context = await build_context(url=f"memory://{results[0].permalink}", project="main", depth=2)
260
+ ```
410
261
 
411
- # Now create the note with both verified and forward relations
412
- content = f"""# Tokyo Neighborhood Guide
262
+ ## Tool Quick Reference
413
263
 
414
- ## Overview
415
- Details about different Tokyo neighborhoods and their unique characteristics.
264
+ | Tool | Purpose | Key Params |
265
+ |------|---------|------------|
266
+ | `write_note` | Create/update | title, content, folder, project |
267
+ | `read_note` | Read content | identifier, project |
268
+ | `edit_note` | Modify existing | identifier, operation, content, project |
269
+ | `search_notes` | Find notes | query, project |
270
+ | `build_context` | Graph traversal | url, depth, project |
271
+ | `recent_activity` | Recent changes | timeframe, project |
272
+ | `list_memory_projects` | Show projects | (none) |
416
273
 
417
- ## Observations
418
- - [area] Shibuya is a busy shopping district #shopping
419
- - [transportation] Yamanote Line connects major neighborhoods #transit
420
- - [recommendation] Visit Shimokitazawa for vintage shopping #unique
421
- - [tip] Get a Suica card for easy train travel #convenience
422
-
423
- {relations_section}
424
- """
425
-
426
- result = await write_note(
427
- title="Tokyo Neighborhood Guide",
428
- content=content,
429
- folder="travel"
430
- )
431
-
432
- # You can check which relations were resolved and which are forward references
433
- if result and 'relations' in result:
434
- resolved = [r['to_name'] for r in result['relations'] if r.get('target_id')]
435
- forward_refs = [r['to_name'] for r in result['relations'] if not r.get('target_id')]
436
-
437
- print(f"Resolved relations: {resolved}")
438
- print(f"Forward references that will be resolved later: {forward_refs}")
439
- ```
274
+ ## memory:// URL Format
440
275
 
441
- ## Error Handling
442
-
443
- Common issues to watch for:
444
-
445
- 1. **Missing Content**
446
- ```python
447
- try:
448
- content = await read_note("Document")
449
- except:
450
- # Try search instead
451
- results = await search_notes(query="Document")
452
- if results and results.primary_results:
453
- # Found something similar
454
- content = await read_note(results.primary_results[0].permalink)
455
- ```
456
-
457
- 2. **Forward References (Unresolved Relations)**
458
- ```python
459
- response = await write_note(
460
- title="My Note",
461
- content="Content with [[Forward Reference]]",
462
- folder="notes"
463
- )
464
- # Check for forward references (unresolved relations)
465
- forward_refs = []
466
- for relation in response.get('relations', []):
467
- if not relation.get('target_id'):
468
- forward_refs.append(relation.get('to_name'))
469
-
470
- if forward_refs:
471
- # This is a feature, not an error! Inform the user about forward references
472
- print(f"Note created with forward references to: {forward_refs}")
473
- print("These will be automatically linked when those notes are created.")
474
-
475
- # Optionally suggest creating those entities now
476
- print("Would you like me to create any of these notes now to complete the connections?")
477
- ```
478
-
479
- 3. **Project Discovery Issues**
480
- ```python
481
- # If user asks about content but no default project is configured
482
- try:
483
- results = await search_notes(query="user query")
484
- except Exception as e:
485
- if "project" in str(e).lower():
486
- # Show available projects and ask user to choose
487
- projects = await list_memory_projects()
488
- print(f"Available projects: {[p.name for p in projects]}")
489
- print("Which project should I search in?")
490
- ```
491
-
492
- 4. **Sync Issues**
493
- ```python
494
- # If information seems outdated
495
- activity = await recent_activity(timeframe="1 hour")
496
- if not activity or not activity.primary_results:
497
- print("It seems there haven't been recent updates. You might need to run 'basic-memory sync'.")
498
- ```
276
+ - `memory://title` - By title
277
+ - `memory://folder/title` - By folder + title
278
+ - `memory://permalink` - By permalink
279
+ - `memory://folder/*` - All in folder
499
280
 
500
- ## Best Practices
281
+ For full documentation: https://docs.basicmemory.com
501
282
 
502
- 1. **Smart Project Management**
503
- - **For new users**: Call `recent_activity()` without project parameter to discover active projects and get recommendations
504
- - **For known projects**: Use explicit project parameters when switching between multiple projects
505
- - **For single-project users**: Rely on default_project_mode for convenience
506
- - **When uncertain**: Use `list_memory_projects()` to show available options and ask the user
507
- - **Remember choices**: Once a user indicates their preferred project, use it consistently throughout the conversation
508
-
509
- 2. **Proactively Record Context**
510
- - Offer to capture important discussions
511
- - Record decisions, rationales, and conclusions
512
- - Link to related topics
513
- - Ask for permission first: "Would you like me to save our discussion about [topic]?"
514
- - Confirm when complete: "I've saved our discussion to Basic Memory"
515
-
516
- 3. **Create a Rich Semantic Graph**
517
- - **Add meaningful observations**: Include at least 3-5 categorized observations in each note
518
- - **Create deliberate relations**: Connect each note to at least 2-3 related entities
519
- - **Use existing entities**: Before creating a new relation, search for existing entities
520
- - **Verify wikilinks**: When referencing `[[Entity]]`, use exact titles of existing notes
521
- - **Check accuracy**: Use `search_notes()` or `recent_activity()` to confirm entity titles
522
- - **Use precise relation types**: Choose specific relation types that convey meaning (e.g., "implements" instead
523
- of "relates_to")
524
- - **Consider bidirectional relations**: When appropriate, create inverse relations in both entities
525
-
526
- 4. **Structure Content Thoughtfully**
527
- - Use clear, descriptive titles
528
- - Organize with logical sections (Context, Decision, Implementation, etc.)
529
- - Include relevant context and background
530
- - Add semantic observations with appropriate categories
531
- - Use a consistent format for similar types of notes
532
- - Balance detail with conciseness
533
-
534
- 5. **Navigate Knowledge Effectively**
535
- - Start with specific searches using `search_notes()`
536
- - Follow relation paths with `build_context()`
537
- - Combine information from multiple sources
538
- - Verify information is current with `recent_activity()`
539
- - Build a complete picture before responding
540
- - Use appropriate project context for searches
541
-
542
- 6. **Help Users Maintain Their Knowledge**
543
- - Suggest organizing related topics across projects when appropriate
544
- - Identify potential duplicates using search
545
- - Recommend adding relations between topics
546
- - Offer to create summaries of scattered information
547
- - Suggest potential missing relations: "I notice this might relate to [topic], would you like me to add that connection?"
548
- - Help users decide when to use explicit vs default project parameters
549
-
550
- Built with ♥️ b
551
- y Basic Machines
283
+ Built with ♥️ by Basic Machines