pin-memory 0.3.1__tar.gz → 0.3.2__tar.gz

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.
@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [Unreleased]
9
+
10
+ ## [0.3.2] - 2026-11-19
11
+
12
+ ### Changed
13
+ - `install` now replaces an existing Pin fragment in place instead of skipping, so
14
+ re-running with a different `--workspace` rebinds the project, and omitting
15
+ `--workspace` clears a stale binding. Surrounding `AGENTS.md` content is preserved.
16
+ - Behavioural constraints (`recall` before the first task, `pin` only when explicitly
17
+ asked) are now also in the MCP tool descriptions, where the model sees them at the
18
+ point of use, not only in the installed `AGENTS.md` fragment.
19
+
20
+ ### Added
21
+ - `--version` CLI option that reports the installed `pin-memory` version.
22
+ - Unit tests for `install`/`AGENTS.md` fragment generation and updating.
23
+
24
+ ### Fixed
25
+ - Deduplicated the repeated sections in `openwiki/workflows/usage.md`.
26
+
8
27
  ## [0.3.1] - 2026-09-28
9
28
 
10
29
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pin-memory
3
- Version: 0.3.1
3
+ Version: 0.3.2
4
4
  Summary: A Memory MCP server for pinning and recalling factoids.
5
5
  Project-URL: Homepage, https://github.com/scartill/pin-memory
6
6
  Project-URL: Changelog, https://github.com/scartill/pin-memory/blob/main/CHANGELOG.md
@@ -39,10 +39,13 @@ uv run pin-memory mcp
39
39
  Pin Memory provides a CLI for managing factoids:
40
40
 
41
41
  ```bash
42
+ # Show installed version
43
+ pin-memory --version
44
+
42
45
  # List all factoids
43
46
  pin-memory show
44
47
 
45
- # Install agent instructions to AGENTS.md
48
+ # Install agent instructions to AGENTS.md (re-run to rebind the workspace)
46
49
  pin-memory install --workspace my-workspace
47
50
 
48
51
  # Launch the MCP server
@@ -86,9 +89,13 @@ Stores a factoid in memory.
86
89
  - `factoid`: The content of the factoid.
87
90
  - `location`: "global", "project", or "workspace/<name>".
88
91
 
92
+ The tool description instructs agents to pin only when explicitly asked, so the model
93
+ sees that constraint at the point where it decides to write.
94
+
89
95
  ### `recall`
90
96
 
91
97
  Recalls all pinned factoids from global, requested workspace, and local project scopes.
98
+ The tool description tells agents to call it before the first task.
92
99
 
93
100
  - `workspace`: Optional name of the workspace.
94
101
 
@@ -27,10 +27,13 @@ uv run pin-memory mcp
27
27
  Pin Memory provides a CLI for managing factoids:
28
28
 
29
29
  ```bash
30
+ # Show installed version
31
+ pin-memory --version
32
+
30
33
  # List all factoids
31
34
  pin-memory show
32
35
 
33
- # Install agent instructions to AGENTS.md
36
+ # Install agent instructions to AGENTS.md (re-run to rebind the workspace)
34
37
  pin-memory install --workspace my-workspace
35
38
 
36
39
  # Launch the MCP server
@@ -74,9 +77,13 @@ Stores a factoid in memory.
74
77
  - `factoid`: The content of the factoid.
75
78
  - `location`: "global", "project", or "workspace/<name>".
76
79
 
80
+ The tool description instructs agents to pin only when explicitly asked, so the model
81
+ sees that constraint at the point where it decides to write.
82
+
77
83
  ### `recall`
78
84
 
79
85
  Recalls all pinned factoids from global, requested workspace, and local project scopes.
86
+ The tool description tells agents to call it before the first task.
80
87
 
81
88
  - `workspace`: Optional name of the workspace.
82
89
 
@@ -2,6 +2,18 @@
2
2
 
3
3
  Pin Memory provides a CLI for managing factoids and installing agent instructions. The CLI is implemented using the `click` library (`/src/pin_memory/server.py`).
4
4
 
5
+ ## Global Options
6
+
7
+ ### `--version`
8
+
9
+ Prints the installed `pin-memory` version and exits.
10
+
11
+ **Example:**
12
+ ```bash
13
+ pin-memory --version
14
+ pin-memory, version 0.3.1
15
+ ```
16
+
5
17
  ## Commands
6
18
 
7
19
  ### `pin-memory show`
@@ -27,7 +39,8 @@ Workspace: my-workspace
27
39
 
28
40
  ### `pin-memory install`
29
41
 
30
- Installs agent instructions to `AGENTS.md`.
42
+ Installs agent instructions to `AGENTS.md`. The fragment is delimited by
43
+ `<!-- pin mcp start -->` and `<!-- pin mcp stop -->`.
31
44
 
32
45
  **Options:**
33
46
  - `--workspace, -w`: Optional workspace name to include in the instructions.
@@ -40,10 +53,14 @@ pin-memory install --workspace my-workspace
40
53
  **Output (`AGENTS.md`):**
41
54
  ```markdown
42
55
  <!-- pin mcp start -->
43
- Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. The Pin workspace for this project is `my-workspace`.
56
+ Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. Do not pin new factoids unless explicitly asked to do so. The Pin workspace for this project is `my-workspace`.
44
57
  <!-- pin mcp stop -->
45
58
  ```
46
59
 
60
+ Re-running the command replaces the existing fragment instead of skipping, so changing
61
+ `--workspace` rebinds the project and omitting it removes a stale binding. Text outside
62
+ the markers is preserved.
63
+
47
64
  ### `pin-memory mcp`
48
65
 
49
66
  Launches the MCP server (stdio).
@@ -12,7 +12,9 @@ It enables **LLMs and agents** to autonomously remember and recall information,
12
12
  - **Pin factoids** in global, workspace-specific, or project-local storage.
13
13
  - **Recall factoids** based on current context (global + workspace + project).
14
14
  - **MCP tools** (`pin`, `recall`) for LLMs to autonomously manage memory.
15
- - **CLI** for managing factoids (`show`, `install`, `mcp`).
15
+ - **CLI** for managing factoids (`show`, `install`, `mcp`); `install` binds a project to
16
+ a workspace via `AGENTS.md`, which tool descriptions cannot do since they are
17
+ server-global.
16
18
  - **Agent integration** for fetching factoids at task start.
17
19
  - **Frontmatter stripping**: Removes YAML frontmatter from factoid files.
18
20
 
@@ -76,11 +78,14 @@ pin-memory show
76
78
  pin-memory install --workspace my-workspace
77
79
  ```
78
80
 
81
+ Re-running the command replaces the fragment in place, so pass a new `--workspace` to
82
+ rebind the project.
83
+
79
84
  **Output (`AGENTS.md`):**
80
85
 
81
86
  ```markdown
82
87
  <!-- pin mcp start -->
83
- Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. The Pin workspace for this project is `my-workspace`.
88
+ Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. Do not pin new factoids unless explicitly asked to do so. The Pin workspace for this project is `my-workspace`.
84
89
  <!-- pin mcp stop -->
85
90
  ```
86
91
 
@@ -0,0 +1,160 @@
1
+ # Usage
2
+
3
+ This page explains how to use Pin Memory for managing factoids and integrating with agents.
4
+
5
+ ## Managing Factoids
6
+
7
+ ### Pin a Factoid
8
+
9
+ Use the `pin` MCP tool to store a factoid in memory.
10
+
11
+ ```json
12
+ {
13
+ "tool": "pin",
14
+ "factoid_name": "api_key",
15
+ "factoid": "sk-12345",
16
+ "location": "global"
17
+ }
18
+ ```
19
+
20
+ **Response:**
21
+
22
+ ```json
23
+ {
24
+ "output": "Factoid 'api_key' pinned to 'global' successfully."
25
+ }
26
+ ```
27
+
28
+ Factoids can also be written manually, as one Markdown file per factoid:
29
+
30
+ ```bash
31
+ mkdir -p ~/.scartill/pin
32
+ echo "sk-12345" > ~/.scartill/pin/api_key.md
33
+ ```
34
+
35
+ ### Recall Factoids
36
+
37
+ Use the `recall` MCP tool to retrieve factoids from the global, workspace, and project scopes in one call.
38
+
39
+ ```json
40
+ {
41
+ "tool": "recall",
42
+ "workspace": "my-workspace"
43
+ }
44
+ ```
45
+
46
+ **Response:**
47
+
48
+ ```json
49
+ {
50
+ "output": "sk-12345\n\nRemember to update the docs!"
51
+ }
52
+ ```
53
+
54
+ YAML frontmatter is stripped from factoid files before the content is returned, so metadata such as `title:` or `tags:` never reaches the agent.
55
+
56
+ ### List All Factoids
57
+
58
+ Use the `show` CLI command to list all factoids grouped by scope.
59
+
60
+ ```bash
61
+ pin-memory show
62
+ ```
63
+
64
+ **Example Output:**
65
+
66
+ ```
67
+ Global Factoids
68
+ ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
69
+ ┃ Name ┃ Content ┃
70
+ ┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
71
+ │ api_key │ sk-12345 │
72
+ └────────────┴───────────────────────────────────────────┘
73
+
74
+ Workspace: my-workspace
75
+ ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
76
+ ┃ Name ┃ Content ┃
77
+ ┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
78
+ │ team_note │ Remember to update the docs! │
79
+ └────────────┴───────────────────────────────────────────┘
80
+ ```
81
+
82
+ ## Scopes
83
+
84
+ | Scope | Description | Storage Location |
85
+ |------------|--------------------------------------------------------------------|-----------------------------------------------|
86
+ | Global | User-wide factoids, available across all projects and workspaces. | `~/.scartill/pin` |
87
+ | Workspace | Factoids specific to a workspace (e.g., a team or project context). | `~/.scartill/pin/workspaces/<workspace_name>` |
88
+ | Project | Factoids local to the current project. | `.pin` in the current working directory |
89
+
90
+ `recall` always reads global and project factoids, plus the workspace passed in its argument.
91
+
92
+ ## Agent Integration
93
+
94
+ ### Install Agent Instructions
95
+
96
+ The `install` command writes a delimited fragment into `AGENTS.md`, binding project
97
+ instructions to the Pin MCP server.
98
+
99
+ ```bash
100
+ pin-memory install --workspace my-workspace
101
+ ```
102
+
103
+ **Output (`AGENTS.md`):**
104
+
105
+ ```markdown
106
+ <!-- pin mcp start -->
107
+ Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. Do not pin new factoids unless explicitly asked to do so. The Pin workspace for this project is `my-workspace`.
108
+ <!-- pin mcp stop -->
109
+ ```
110
+
111
+ The command is idempotent: re-running it replaces the existing fragment in place rather
112
+ than skipping, so changing `--workspace` rebinds the project, and omitting `--workspace`
113
+ removes a previously installed binding. Text outside the markers is left untouched.
114
+
115
+ Why this exists alongside the tool descriptions:
116
+
117
+ - **Timing.** Tool descriptions only inform a decision once the model already considers a
118
+ tool relevant. The fragment tells the agent to `recall` *before* the first task, which
119
+ no server-side description can enforce.
120
+ - **Project binding.** The workspace name is per-project configuration, while an MCP tool
121
+ description is server-global and static.
122
+ - **Clients without MCP.** Agents that never load the server still read `AGENTS.md`.
123
+
124
+ ### Fetching Factoids at Task Start
125
+
126
+ When an agent starts a task, it should:
127
+
128
+ 1. Use the `recall` MCP tool to fetch factoids from global, workspace, and project scopes.
129
+ 2. Use the factoids as **important instructions** for the task.
130
+
131
+ ### Example Workflow
132
+
133
+ 1. **Pin factoids** for the workspace:
134
+ ```json
135
+ {
136
+ "tool": "pin",
137
+ "factoid_name": "team_note",
138
+ "factoid": "Remember to update the docs!",
139
+ "location": "workspace/my-workspace"
140
+ }
141
+ ```
142
+
143
+ 2. **Install agent instructions** for the workspace:
144
+ ```bash
145
+ pin-memory install --workspace my-workspace
146
+ ```
147
+
148
+ 3. **Agent fetches factoids** at task start:
149
+ ```json
150
+ {
151
+ "tool": "recall",
152
+ "workspace": "my-workspace"
153
+ }
154
+ ```
155
+
156
+ 4. **Agent uses factoids** as instructions for the task.
157
+
158
+ ## Source Reference
159
+
160
+ - [`/src/pin_memory/server.py`](file:///src/pin_memory/server.py): Core logic and CLI.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pin-memory"
3
- version = "0.3.1"
3
+ version = "0.3.2"
4
4
  description = "A Memory MCP server for pinning and recalling factoids."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.10"
@@ -1,3 +1,4 @@
1
+ from importlib import metadata
1
2
  from pathlib import Path
2
3
  from typing import Literal
3
4
 
@@ -9,6 +10,12 @@ from rich.console import Console
9
10
  from rich.table import Table
10
11
 
11
12
 
13
+ try:
14
+ __version__ = metadata.version("pin-memory")
15
+ except metadata.PackageNotFoundError:
16
+ __version__ = "unknown"
17
+
18
+
12
19
  class MemoryManager:
13
20
  """Manages factoids stored in various scopes."""
14
21
 
@@ -61,7 +68,9 @@ class MemoryManager:
61
68
  @staticmethod
62
69
  def _strip_frontmatter(text: str) -> str:
63
70
  """Remove YAML frontmatter (--- delimited block at start of text)."""
64
- return re.sub(r"\A---\s*\n(.*?\n)?---\s*\n?", "", text, count=1, flags=re.DOTALL)
71
+ return re.sub(
72
+ r"\A---\s*\n(.*?\n)?---\s*\n?", "", text, count=1, flags=re.DOTALL
73
+ )
65
74
 
66
75
  def _get_factoids(self, target_dir: Path) -> list[dict]:
67
76
  """Get all factoids from a specific directory as list of dicts {name, content}."""
@@ -128,7 +137,70 @@ class MemoryManager:
128
137
  return results
129
138
 
130
139
 
140
+ PIN_START_MARKER = "<!-- pin mcp start -->"
141
+ PIN_STOP_MARKER = "<!-- pin mcp stop -->"
142
+
143
+ PIN_INSTRUCTIONS = (
144
+ "Before starting the first task, fetch all global and project factoids via Pin MCP "
145
+ "and use them as **important** instructions. Do not pin new factoids unless "
146
+ "explicitly asked to do so."
147
+ )
148
+
149
+
150
+ def build_fragment(workspace: str | None = None) -> str:
151
+ """Build the agent instructions fragment, optionally binding a workspace."""
152
+ instruction = PIN_INSTRUCTIONS
153
+ if workspace:
154
+ instruction += f" The Pin workspace for this project is `{workspace}`."
155
+ return f"{PIN_START_MARKER}\n{instruction}\n{PIN_STOP_MARKER}\n"
156
+
157
+
158
+ def upsert_fragment(content: str, fragment: str) -> str:
159
+ """Replace an existing Pin fragment in place, or append a new one."""
160
+ pattern = re.compile(
161
+ re.escape(PIN_START_MARKER) + r".*?" + re.escape(PIN_STOP_MARKER) + r"\n?",
162
+ re.DOTALL,
163
+ )
164
+ if pattern.search(content):
165
+ return pattern.sub(lambda _: fragment, content, count=1)
166
+
167
+ separator = ""
168
+ if content and not content.endswith("\n"):
169
+ separator = "\n"
170
+ return f"{content}{separator}\n{fragment}"
171
+
172
+
173
+ def install_instructions(
174
+ agents_path: Path, workspace: str | None = None
175
+ ) -> tuple[bool, str]:
176
+ """Create or update the Pin fragment in an agent instructions file.
177
+
178
+ Returns a (changed, message) tuple.
179
+ """
180
+ fragment = build_fragment(workspace)
181
+ name = agents_path.name
182
+
183
+ if agents_path.exists():
184
+ content = agents_path.read_text(encoding="utf-8")
185
+ updated = upsert_fragment(content, fragment)
186
+ if updated == content:
187
+ return False, f"{name} already contains the current Pin MCP fragment."
188
+ try:
189
+ agents_path.write_text(updated, encoding="utf-8")
190
+ except OSError as e:
191
+ return False, f"Error updating {name}: {e}"
192
+ action = "Updated" if PIN_START_MARKER in content else "Added"
193
+ return True, f"{action} Pin MCP fragment in {name}."
194
+
195
+ try:
196
+ agents_path.write_text(fragment, encoding="utf-8")
197
+ except OSError as e:
198
+ return False, f"Error creating {name}: {e}"
199
+ return True, f"Created {name} with Pin MCP fragment."
200
+
201
+
131
202
  @click.group()
203
+ @click.version_option(version=__version__, prog_name="pin-memory")
132
204
  def cli():
133
205
  """Pin MCP – Memory management across global, workspace, and project scopes."""
134
206
  pass
@@ -177,47 +249,19 @@ def show():
177
249
  "--workspace", "-w", help="Optional workspace name to include in the instructions."
178
250
  )
179
251
  def install(workspace: str | None) -> None:
180
- """Add agent instructions fragment to AGENTS.md."""
181
- console = Console()
182
- agents_file = Path("AGENTS.md")
183
-
184
- start_marker = "<!-- pin mcp start -->"
185
- stop_marker = "<!-- pin mcp stop -->"
186
-
187
- instruction = (
188
- "Before starting the first task, fetch all global and project factoids via Pin MCP "
189
- "and use them as **important** instructions. Do not pin new factoids unless "
190
- "explicitly asked to do so."
191
- )
192
- if workspace:
193
- instruction += f" The Pin workspace for this project is `{workspace}`."
252
+ """Add or update the agent instructions fragment in AGENTS.md.
194
253
 
195
- fragment = f"{start_marker}\n{instruction}\n{stop_marker}\n"
196
-
197
- if agents_file.exists():
198
- content = agents_file.read_text(encoding="utf-8")
199
- if start_marker in content:
200
- console.print(
201
- "[yellow]AGENTS.md already contains the Pin MCP fragment. Skipping.[/yellow]"
202
- )
203
- return
204
- # Append to existing file
205
- try:
206
- with agents_file.open("a", encoding="utf-8") as f:
207
- # Ensure we start on a new line if the file doesn't end with one
208
- if content and not content.endswith("\n"):
209
- f.write("\n")
210
- f.write(f"\n{fragment}")
211
- console.print("[green]Pin MCP fragment added to AGENTS.md.[/green]")
212
- except Exception as e:
213
- console.print(f"[red]Error updating AGENTS.md: {e}[/red]")
254
+ Re-running updates the existing fragment in place, so changing
255
+ --workspace rebinds the project instead of being ignored.
256
+ """
257
+ changed, message = install_instructions(Path("AGENTS.md"), workspace)
258
+ console = Console()
259
+ if changed:
260
+ console.print(f"[green]{message}[/green]")
261
+ elif message.startswith("Error"):
262
+ console.print(f"[red]{message}[/red]")
214
263
  else:
215
- # Create new file
216
- try:
217
- agents_file.write_text(fragment, encoding="utf-8")
218
- console.print("[green]Created AGENTS.md with Pin MCP fragment.[/green]")
219
- except Exception as e:
220
- console.print(f"[red]Error creating AGENTS.md: {e}[/red]")
264
+ console.print(f"[yellow]{message}[/yellow]")
221
265
 
222
266
 
223
267
  @cli.command("mcp")
@@ -232,6 +276,9 @@ def mcp_cmd():
232
276
  ) -> str:
233
277
  """Store a factoid in memory.
234
278
 
279
+ Only pin when explicitly asked to do so; never pin unprompted, and never pin
280
+ credentials or secrets unless the user names the factoid themselves.
281
+
235
282
  If asked to pin to a workspace, use "workspace/<name>" for location. Example: "workspace/my-workspace".
236
283
 
237
284
  If asked to pin locally or for the current projects, use "project" for location.
@@ -247,6 +294,9 @@ def mcp_cmd():
247
294
  def recall(workspace: str | None = None) -> str:
248
295
  """Recall pinned factoids.
249
296
 
297
+ Call this before starting the first task in a session, and use the result as
298
+ important instructions for the rest of the work.
299
+
250
300
  Returns global, requested workspace, and local project factoids.
251
301
 
252
302
  Args:
@@ -2,7 +2,18 @@ import unittest
2
2
  from pathlib import Path
3
3
  import shutil
4
4
  import tempfile
5
- from pin_memory.server import MemoryManager
5
+
6
+ from click.testing import CliRunner
7
+ from pin_memory.server import (
8
+ __version__,
9
+ cli,
10
+ PIN_START_MARKER,
11
+ PIN_STOP_MARKER,
12
+ MemoryManager,
13
+ build_fragment,
14
+ install_instructions,
15
+ upsert_fragment,
16
+ )
6
17
 
7
18
 
8
19
  class TestMemoryManager(unittest.TestCase):
@@ -59,7 +70,6 @@ class TestMemoryManager(unittest.TestCase):
59
70
  self.assertIn("project fact", output)
60
71
  self.assertEqual(output, "global fact\n\nproject fact")
61
72
 
62
-
63
73
  def test_strip_frontmatter_removes_yaml_block(self):
64
74
  """Verify _strip_frontmatter removes YAML frontmatter from content."""
65
75
  text = "---\ntitle: Test\ndate: 2024-01-01\n---\nActual content here."
@@ -120,5 +130,96 @@ class TestMemoryManager(unittest.TestCase):
120
130
  self.assertEqual(output, "Remember this.")
121
131
 
122
132
 
133
+ class TestInstallInstructions(unittest.TestCase):
134
+ def setUp(self):
135
+ self.test_dir = Path(tempfile.mkdtemp())
136
+ self.agents_file = self.test_dir / "AGENTS.md"
137
+
138
+ def tearDown(self):
139
+ shutil.rmtree(self.test_dir)
140
+
141
+ def test_creates_file_with_fragment(self):
142
+ changed, message = install_instructions(self.agents_file)
143
+ self.assertTrue(changed)
144
+ self.assertIn("Created", message)
145
+ content = self.agents_file.read_text(encoding="utf-8")
146
+ self.assertTrue(content.startswith(PIN_START_MARKER))
147
+ self.assertTrue(content.rstrip().endswith(PIN_STOP_MARKER))
148
+
149
+ def test_workspace_binding_written(self):
150
+ install_instructions(self.agents_file, workspace="my-workspace")
151
+ content = self.agents_file.read_text(encoding="utf-8")
152
+ self.assertIn("The Pin workspace for this project is `my-workspace`.", content)
153
+
154
+ def test_appends_to_existing_content(self):
155
+ self.agents_file.write_text("# Project\n\nRules.", encoding="utf-8")
156
+ changed, message = install_instructions(self.agents_file)
157
+ self.assertTrue(changed)
158
+ self.assertIn("Added", message)
159
+ content = self.agents_file.read_text(encoding="utf-8")
160
+ self.assertTrue(content.startswith("# Project\n\nRules.\n"))
161
+ self.assertIn(PIN_START_MARKER, content)
162
+
163
+ def test_rerun_is_idempotent(self):
164
+ install_instructions(self.agents_file, workspace="first")
165
+ changed, message = install_instructions(self.agents_file, workspace="first")
166
+ self.assertFalse(changed)
167
+ self.assertIn("already contains", message)
168
+
169
+ def test_rerun_with_new_workspace_rebinds(self):
170
+ install_instructions(self.agents_file, workspace="first")
171
+ changed, message = install_instructions(self.agents_file, workspace="second")
172
+ self.assertTrue(changed)
173
+ self.assertIn("Updated", message)
174
+ content = self.agents_file.read_text(encoding="utf-8")
175
+ self.assertEqual(content.count(PIN_START_MARKER), 1)
176
+ self.assertIn("`second`", content)
177
+ self.assertNotIn("`first`", content)
178
+
179
+ def test_rerun_without_workspace_clears_binding(self):
180
+ install_instructions(self.agents_file, workspace="first")
181
+ install_instructions(self.agents_file)
182
+ content = self.agents_file.read_text(encoding="utf-8")
183
+ self.assertNotIn("The Pin workspace for this project", content)
184
+
185
+ def test_fragment_between_surrounding_text_preserved(self):
186
+ before = "# Project\n\nIntro.\n\n"
187
+ after = "\n## Later notes\n\nKeep me.\n"
188
+ install_instructions(self.agents_file, workspace="first")
189
+ original = self.agents_file.read_text(encoding="utf-8")
190
+ self.agents_file.write_text(before + original + after, encoding="utf-8")
191
+ install_instructions(self.agents_file, workspace="second")
192
+ content = self.agents_file.read_text(encoding="utf-8")
193
+ self.assertTrue(content.startswith(before))
194
+ self.assertTrue(content.endswith(after.lstrip("\n")) or after in content)
195
+ self.assertIn("`second`", content)
196
+ self.assertEqual(content.count(PIN_START_MARKER), 1)
197
+
198
+ def test_build_fragment_markers(self):
199
+ fragment = build_fragment()
200
+ self.assertEqual(
201
+ fragment, f"{PIN_START_MARKER}\n{_instructions()}\n{PIN_STOP_MARKER}\n"
202
+ )
203
+
204
+ def test_upsert_preserves_missing_trailing_newline(self):
205
+ content = "# Project\n\nRules."
206
+ updated = upsert_fragment(content, build_fragment())
207
+ self.assertTrue(updated.startswith("# Project\n\nRules.\n\n"))
208
+
209
+
210
+ class TestCLI(unittest.TestCase):
211
+ def test_version_option(self):
212
+ runner = CliRunner()
213
+ result = runner.invoke(cli, ["--version"])
214
+ self.assertEqual(result.exit_code, 0)
215
+ self.assertIn("pin-memory, version", result.output)
216
+
217
+
218
+ def _instructions() -> str:
219
+ from pin_memory.server import PIN_INSTRUCTIONS
220
+
221
+ return PIN_INSTRUCTIONS
222
+
223
+
123
224
  if __name__ == "__main__":
124
225
  unittest.main()
@@ -1,5 +1,5 @@
1
1
  version = 1
2
- revision = 2
2
+ revision = 5
3
3
  requires-python = ">=3.10"
4
4
 
5
5
  [[package]]
@@ -220,7 +220,7 @@ name = "exceptiongroup"
220
220
  version = "1.3.1"
221
221
  source = { registry = "https://pypi.org/simple" }
222
222
  dependencies = [
223
- { name = "typing-extensions", marker = "python_full_version < '3.13'" },
223
+ { name = "typing-extensions" },
224
224
  ]
225
225
  sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
226
226
  wheels = [
@@ -381,7 +381,7 @@ wheels = [
381
381
 
382
382
  [[package]]
383
383
  name = "pin-memory"
384
- version = "0.3.1"
384
+ version = "0.3.2"
385
385
  source = { editable = "." }
386
386
  dependencies = [
387
387
  { name = "click" },
@@ -1,346 +0,0 @@
1
- # Usage
2
-
3
- This page explains how to use Pin Memory for managing factoids and integrating with agents.
4
-
5
- ## Managing Factoids
6
-
7
- ### Pin a Factoid
8
-
9
- Use the `pin` MCP tool or CLI to store a factoid in memory.
10
-
11
- #### MCP Request
12
-
13
- ```json
14
- {
15
- "tool": "pin",
16
- "factoid_name": "api_key",
17
- "factoid": "sk-12345",
18
- "location": "global"
19
- }
20
- ```
21
-
22
- **Response:**
23
-
24
- ```json
25
- {
26
- "output": "Factoid 'api_key' pinned to 'global' successfully."
27
- }
28
- ```
29
-
30
- #### CLI Equivalent
31
-
32
- ```bash
33
- pin-memory mcp
34
- ```
35
-
36
- Then send the MCP request above.
37
-
38
- ### Recall Factoids
39
-
40
- Use the `recall` MCP tool to retrieve factoids from global, workspace, and project scopes.
41
-
42
- #### MCP Request
43
-
44
- ```json
45
- {
46
- "tool": "recall",
47
- "workspace": "my-workspace"
48
- }
49
- ```
50
-
51
- **Response:**
52
-
53
- ```json
54
- {
55
- "output": "sk-12345\n\nRemember to update the docs!"
56
- }
57
- ```
58
-
59
- #### CLI Equivalent
60
-
61
- ```bash
62
- pin-memory show
63
- ```
64
-
65
- ### List All Factoids
66
-
67
- Use the `show` CLI command to list all factoids grouped by scope.
68
-
69
- ```bash
70
- pin-memory show
71
- ```
72
-
73
- **Example Output:**
74
-
75
- ```
76
- Global Factoids
77
- ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
78
- ┃ Name ┃ Content ┃
79
- ┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
80
- │ api_key │ sk-12345 │
81
- └────────────┴───────────────────────────────────────────┘
82
-
83
- Workspace: my-workspace
84
- ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
85
- ┃ Name ┃ Content ┃
86
- ┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
87
- │ team_note │ Remember to update the docs! │
88
- └────────────┴───────────────────────────────────────────┘
89
- ```
90
-
91
- ## Agent Integration
92
-
93
- ### Install Agent Instructions
94
-
95
- Use the `install` CLI command to add a fragment to `AGENTS.md` that instructs agents to fetch factoids at the start of tasks.
96
-
97
- ```bash
98
- pin-memory install --workspace my-workspace
99
- ```
100
-
101
- **Output (`AGENTS.md`):**
102
-
103
- ```markdown
104
- <!-- pin mcp start -->
105
- Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. The Pin workspace for this project is `my-workspace`.
106
- <!-- pin mcp stop -->
107
- ```
108
-
109
- ### Fetching Factoids at Task Start
110
-
111
- When an agent starts a task, it should:
112
- 1. Use the `recall` MCP tool to fetch factoids from global, workspace, and project scopes.
113
- 2. Use the factoids as **important instructions** for the task.
114
-
115
- **Example MCP Request:**
116
-
117
- ```json
118
- {
119
- "tool": "recall",
120
- "workspace": "my-workspace"
121
- }
122
- ```
123
-
124
- ## Scopes
125
-
126
- | Scope | Description | Storage Location |
127
- |------------|-----------------------------------------------------------------------------|---------------------------------------------------|
128
- | Global | User-wide factoids, available across all projects and workspaces. | `~/.scartill/pin` |
129
- | Workspace | Factoids specific to a workspace (e.g., a team or project context). | `~/.scartill/pin/workspaces/<workspace_name>` |
130
- | Project | Factoids local to the current project. | `.pin` in the current working directory |
131
-
132
- ## Source Reference
133
-
134
- - [`/src/pin_memory/server.py`](file:///src/pin_memory/server.py): Core logic and CLI.
135
-
136
- ## Managing Factoids
137
-
138
- ### Pin a Factoid
139
-
140
- Use the `pin` MCP tool to store a factoid in memory.
141
-
142
- **Example:**
143
-
144
- ```bash
145
- pin-memory mcp
146
- ```
147
-
148
- **MCP Request:**
149
- ```json
150
- {
151
- "tool": "pin",
152
- "factoid_name": "api_key",
153
- "factoid": "sk-12345",
154
- "location": "global"
155
- }
156
- ```
157
-
158
- ### Recall Factoids
159
-
160
- Use the `recall` MCP tool to retrieve factoids.
161
-
162
- **Example:**
163
-
164
- ```json
165
- {
166
- "tool": "recall",
167
- "workspace": "my-workspace"
168
- }
169
- ```
170
-
171
- **Response:**
172
- ```json
173
- {
174
- "output": "sk-12345\n\nRemember to update the docs!"
175
- }
176
- ```
177
-
178
- ### List All Factoids
179
-
180
- Use the `show` CLI command to list all factoids grouped by scope.
181
-
182
- ```bash
183
- pin-memory show
184
- ```
185
-
186
- **Example Output:**
187
- ```
188
- Global Factoids
189
- ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
190
- ┃ Name ┃ Content ┃
191
- ┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
192
- │ api_key │ sk-12345 │
193
- └────────────┴───────────────────────────────────────────┘
194
-
195
- Workspace: my-workspace
196
- ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
197
- ┃ Name ┃ Content ┃
198
- ┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
199
- │ team_note │ Remember to update the docs! │
200
- └────────────┴───────────────────────────────────────────┘
201
- ```
202
-
203
- ## Agent Integration
204
-
205
- ### Install Agent Instructions
206
-
207
- Use the `install` CLI command to add Pin Memory instructions to `AGENTS.md`.
208
-
209
- **Example:**
210
-
211
- ```bash
212
- pin-memory install --workspace my-workspace
213
- ```
214
-
215
- **Output (`AGENTS.md`):**
216
-
217
- ```markdown
218
- <!-- pin mcp start -->
219
- Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. The Pin workspace for this project is `my-workspace`.
220
- <!-- pin mcp stop -->
221
- ```
222
-
223
- ### Fetching Factoids at Task Start
224
-
225
- When an agent starts a task, it should:
226
- 1. Use the `recall` MCP tool to fetch factoids from global, workspace, and project scopes.
227
- 2. Use the factoids as **important instructions** for the task.
228
-
229
- **Example Workflow:**
230
-
231
- ```python
232
- # Agent fetches factoids at task start
233
- factoids = recall("my-workspace")
234
- # factoids = "sk-12345\n\nRemember to update the docs!"
235
- ```
236
-
237
- ## Source Reference
238
-
239
- - [`/src/pin_memory/server.py`](file:///src/pin_memory/server.py): CLI and MCP tools.
240
-
241
- ## Managing Factoids
242
-
243
- ### Pin a Factoid
244
-
245
- Use the MCP `pin` tool or manually create a Markdown file in the target scope:
246
-
247
- ```bash
248
- # Using MCP
249
- {
250
- "tool": "pin",
251
- "factoid_name": "api_key",
252
- "factoid": "sk-12345",
253
- "location": "global"
254
- }
255
- ```
256
-
257
- **Manual:**
258
- ```bash
259
- mkdir -p ~/.scartill/pin
260
- echo "sk-12345" > ~/.scartill/pin/api_key.md
261
- ```
262
-
263
- ### Recall Factoids
264
-
265
- Use the MCP `recall` tool or the CLI `show` command:
266
-
267
- ```bash
268
- # Using MCP
269
- {
270
- "tool": "recall",
271
- "workspace": "my-workspace"
272
- }
273
- ```
274
-
275
- **CLI:**
276
- ```bash
277
- pin-memory show
278
- ```
279
-
280
- ### Scopes
281
-
282
- | Scope | Example Location | Use Case |
283
- |------------|-------------------------------------------|-------------------------------------------|
284
- | Global | `~/.scartill/pin/api_key.md` | User-wide preferences or secrets. |
285
- | Workspace | `~/.scartill/pin/workspaces/dev/api.md` | Team or project-specific instructions. |
286
- | Project | `.pin/local_note.md` | Project-local context. |
287
-
288
- ## Agent Integration
289
-
290
- ### Install Agent Instructions
291
-
292
- Run the following command to install agent instructions to `AGENTS.md`:
293
-
294
- ```bash
295
- pin-memory install --workspace my-workspace
296
- ```
297
-
298
- This adds a fragment to `AGENTS.md`:
299
-
300
- ```markdown
301
- <!-- pin mcp start -->
302
- Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. The Pin workspace for this project is `my-workspace`.
303
- <!-- pin mcp stop -->
304
- ```
305
-
306
- ### Fetch Factoids at Task Start
307
-
308
- Agents should use the `recall` tool at the start of tasks to fetch factoids:
309
-
310
- ```json
311
- {
312
- "tool": "recall",
313
- "workspace": "my-workspace"
314
- }
315
- ```
316
-
317
- ### Example Workflow
318
-
319
- 1. **Pin factoids** for the workspace:
320
- ```json
321
- {
322
- "tool": "pin",
323
- "factoid_name": "team_note",
324
- "factoid": "Remember to update the docs!",
325
- "location": "workspace/my-workspace"
326
- }
327
- ```
328
-
329
- 2. **Install agent instructions** for the workspace:
330
- ```bash
331
- pin-memory install --workspace my-workspace
332
- ```
333
-
334
- 3. **Agent fetches factoids** at task start:
335
- ```json
336
- {
337
- "tool": "recall",
338
- "workspace": "my-workspace"
339
- }
340
- ```
341
-
342
- 4. **Agent uses factoids** as instructions for the task.
343
-
344
- ## Source Reference
345
-
346
- - [`/src/pin_memory/server.py`](file:///src/pin_memory/server.py): Memory management and MCP tools.
File without changes
File without changes
File without changes