@staix/vault-mem 0.10.2 → 0.11.0
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.
- package/CHANGELOG.md +5 -0
- package/README.md +4 -4
- package/bin/vmem.js +4 -1
- package/package.json +2 -2
- package/src/amem/host-api.ts +23 -0
- package/src/amem/seam.ts +10 -4
- package/src/cli-output.ts +2 -2
- package/src/cli.ts +2 -1
- package/src/platform.ts +6 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [0.11.0] - 2026-11-21
|
|
6
|
+
|
|
7
|
+
- N-1: 0.10.x pins agent-mem 0.32.0 while 0.11.0 accepts `>=0.33.0 <1.0.0` when its host API includes version 1. Both share the same vault index, configuration, CLI and MCP contracts; 0.11.0 status and doctor additionally report the loaded agent-mem version and host API. Neither release raises agent-mem format floors or changes placement writer attestation.
|
|
8
|
+
- Check agent-mem host API compatibility before opening its stores. New compatible agent-mem minors are accepted when vmem is installed or updated; an existing installation retains its resolved version until updated.
|
|
9
|
+
|
|
5
10
|
## [0.10.2] - 2026-11-21
|
|
6
11
|
|
|
7
12
|
- Raise the exact `@staix/agent-mem` runtime pin from 0.30.0 to 0.32.0. The 0.31.0 release adds an optional reader lease signature and a held placement outcome; 0.32.0 adds catalog and placement view exports and optional refusal details. Both releases are additive for library consumers, preserve shared storage formats and do not raise the home format floor.
|
package/README.md
CHANGED
|
@@ -15,8 +15,8 @@ vmem --version
|
|
|
15
15
|
|
|
16
16
|
```sh
|
|
17
17
|
vmem vaults add personal /absolute/vault --kind personal --write mcp # the directory must contain notes/
|
|
18
|
-
vmem status # home, registered vaults and health
|
|
19
|
-
vmem doctor # path, remote, registry, pending-tidy and spec-source checks; exits 1 when unhealthy
|
|
18
|
+
vmem status # home, agent-mem version, registered vaults and health
|
|
19
|
+
vmem doctor # agent-mem version, path, remote, registry, pending-tidy and spec-source checks; exits 1 when unhealthy
|
|
20
20
|
vmem setup claude # dry run: the MCP entry it would add
|
|
21
21
|
vmem setup claude --apply # register `vmem mcp` in the host, then restart the host session
|
|
22
22
|
vmem search personal "project discovery"
|
|
@@ -70,7 +70,7 @@ Output: every command prints text for people by default, following agent-hub's C
|
|
|
70
70
|
|
|
71
71
|
## Library
|
|
72
72
|
|
|
73
|
-
The only runtime dependency is the
|
|
73
|
+
The only runtime dependency is the first-party range <!-- facts:amem-pin -->`@staix/agent-mem@>=0.33.0 <1.0.0`<!-- /facts:amem-pin -->; host API 1 is checked at load before any agent-mem store opens. Registry commands do not load the agent-mem root. New compatible minors are resolved on installation or update; an existing installation keeps its resolved version. Public library exports (`@staix/vault-mem`, from `src/index.ts`) cover configuration and home resolution, registry operations, frontmatter, link resolution and the derived index, validated writes, the append-only log, the MCP server and its vault tools, host setup, the CLI command table and completion, promotion from agent-mem and to org vaults, lint and graph analysis, sync, source references, migration tidy, the temporal assertion journal and its evaluation, and the spec source registry, graph, validation and freshness. `@staix/vault-mem/ui-plugin` is the console plugin entry (see [Console plugin](docs/reference/mcp-and-setup.md#console-plugin)). No console bin is shipped. Exported functions and constants by module:
|
|
74
74
|
<!-- facts:exports -->
|
|
75
75
|
|
|
76
76
|
- `src/assertion-read.ts`: `readAssertions`, `ASSERTIONS_PAGE_LIMIT`
|
|
@@ -117,4 +117,4 @@ bun bin/vmem.js --help # run from a checkout
|
|
|
117
117
|
bun run check
|
|
118
118
|
```
|
|
119
119
|
|
|
120
|
-
`bun run check` needs Bun, git and tar: strict types, import boundaries, README facts, documentation freshness, tests, a package dry-run and a clean installed CLI/MCP smoke (the tarball install needs network access to resolve the
|
|
120
|
+
`bun run check` needs Bun, git and tar: strict types, import boundaries, README facts, documentation freshness, tests, a package dry-run and a clean installed CLI/MCP smoke (the tarball install needs network access to resolve the dependency range). Node/npm are used only by the release workflow. CI runs on Ubuntu for pull requests (macOS too when the `ci:macos` label is added), and on Ubuntu and macOS for pushes to `main` and releases. Generated facts blocks in README.md and docs/reference change only through `bun scripts/readme-facts.ts --write`. Contributor rules are in [AGENTS.md](AGENTS.md) and [REVIEW.md](REVIEW.md); release gates in [docs/release-readiness.md](docs/release-readiness.md).
|
package/bin/vmem.js
CHANGED
|
@@ -4,7 +4,10 @@ if (!version || Number(version[1]) < 1 || (Number(version[1]) === 1 && (Number(v
|
|
|
4
4
|
console.error("vmem: Bun >=1.4.2 is required. Install Bun: https://bun.sh");
|
|
5
5
|
process.exit(1);
|
|
6
6
|
}
|
|
7
|
-
|
|
7
|
+
let cli;
|
|
8
|
+
try { cli = await import("../src/cli.ts"); }
|
|
9
|
+
catch (error) { console.error(`vmem: ${error instanceof Error ? error.message : "failed to load"}`); process.exit(1); }
|
|
10
|
+
const { main, mainAsync, reportError, runMcp } = cli;
|
|
8
11
|
const { resolveColor, takeColorFlag } = await import("../src/text-output.ts");
|
|
9
12
|
const argv = process.argv.slice(2);
|
|
10
13
|
// `--color=` may stand anywhere, so the dispatch looks at the words without it; main/mainAsync take it off again.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@staix/vault-mem",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"description": "Validated Obsidian-compatible knowledge vaults for agents and people",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
"bun": ">=1.4.2"
|
|
13
13
|
},
|
|
14
14
|
"dependencies": {
|
|
15
|
-
"@staix/agent-mem": "0.
|
|
15
|
+
"@staix/agent-mem": ">=0.33.0 <1.0.0"
|
|
16
16
|
},
|
|
17
17
|
"devDependencies": {
|
|
18
18
|
"@staix/agent-console": "github:STAIxBWLB/agent-console#c978b31",
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs";
|
|
2
|
+
import { createRequire } from "node:module";
|
|
3
|
+
import { dirname, join } from "node:path";
|
|
4
|
+
|
|
5
|
+
/** Read the version of the package containing the resolved entry, not the host's declared range. */
|
|
6
|
+
export function installedAmemVersion(entry: string): string {
|
|
7
|
+
let dir = dirname(entry);
|
|
8
|
+
for (;;) {
|
|
9
|
+
try {
|
|
10
|
+
const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
|
|
11
|
+
if (manifest.name === "@staix/agent-mem" && typeof manifest.version === "string") return manifest.version;
|
|
12
|
+
} catch { /* Continue to the package root. */ }
|
|
13
|
+
const parent = dirname(dir);
|
|
14
|
+
if (parent === dir) throw new Error("agent-mem: cannot determine installed version; reinstall @staix/agent-mem");
|
|
15
|
+
dir = parent;
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
export const amemVersion = () => installedAmemVersion(createRequire(import.meta.url).resolve("@staix/agent-mem/platform"));
|
|
19
|
+
export function checkHostApi(api: { HOST_API_MIN?: unknown; HOST_API_VERSION?: unknown }, version: string): void {
|
|
20
|
+
const min = api.HOST_API_MIN, max = api.HOST_API_VERSION;
|
|
21
|
+
if (Number.isSafeInteger(min) && Number.isSafeInteger(max) && (min as number) >= 1 && (min as number) <= 1 && (max as number) >= 1) return;
|
|
22
|
+
throw new Error(`agent-mem ${version}: host API ${String(min ?? "missing")}..${String(max ?? "missing")} is incompatible with vmem host API 1; update @staix/agent-mem or @staix/vault-mem to compatible versions`);
|
|
23
|
+
}
|
package/src/amem/seam.ts
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
* is indexed or copied here: the seam lists candidates from amem's own selection and records amem's own vault link.
|
|
5
5
|
*/
|
|
6
6
|
import type { MemoryStore, View } from "@staix/agent-mem";
|
|
7
|
+
import { amemVersion, checkHostApi } from "./host-api.ts";
|
|
7
8
|
|
|
8
9
|
export interface AmemCandidate { id: string; project: string; kind: string; title: string | null; text: string; about: string[]; at: string }
|
|
9
10
|
export interface AmemSeam {
|
|
@@ -18,13 +19,18 @@ export interface AmemSeam {
|
|
|
18
19
|
export interface AmemOptions { env?: NodeJS.ProcessEnv; project?: string; cwd?: string; piiPatterns?: string[] }
|
|
19
20
|
const ID = /^[a-f0-9]{32}$/;
|
|
20
21
|
/** Load the agent-mem root now. `vmem mcp` calls it at start; every other caller keeps the lazy load. */
|
|
21
|
-
|
|
22
|
+
async function loadAmem() {
|
|
23
|
+
const amem = await import("@staix/agent-mem");
|
|
24
|
+
checkHostApi(amem, amemVersion());
|
|
25
|
+
return amem;
|
|
26
|
+
}
|
|
27
|
+
export async function preloadAmem(): Promise<void> { await loadAmem(); }
|
|
22
28
|
function view(value: View): AmemCandidate {
|
|
23
29
|
return { id: value.id, project: value.project, kind: value.kind, title: value.title, text: value.text, about: value.about.map(node => String(node)), at: value.at };
|
|
24
30
|
}
|
|
25
31
|
/** Open the curated store of one project. Listing and linking both require the generation profile. */
|
|
26
32
|
export async function openAmem(options: AmemOptions = {}): Promise<AmemSeam> {
|
|
27
|
-
const amem = await
|
|
33
|
+
const amem = await loadAmem();
|
|
28
34
|
const env = options.env ?? process.env, base = amem.memoryHome(env);
|
|
29
35
|
const project = options.project ?? amem.memoryProjectKey(options.cwd ?? process.cwd());
|
|
30
36
|
if (!project.trim() || project.length > 400) throw new Error("amem: invalid project key");
|
|
@@ -60,7 +66,7 @@ const MINE_EVENTS = new Set(["UserPromptSubmit", "observation", "summary", "Reca
|
|
|
60
66
|
* exist: an absent home, a capture-only shard or an unsplit home without curated logs yields no rows, never a new store.
|
|
61
67
|
*/
|
|
62
68
|
export async function readAmemForMining(options: { env?: NodeJS.ProcessEnv; project?: string; since: string; piiPatterns?: string[]; maxCaptureRows?: number }): Promise<MineAmemRead> {
|
|
63
|
-
const amem = await
|
|
69
|
+
const amem = await loadAmem();
|
|
64
70
|
const { existsSync } = await import("node:fs"), { basename, join } = await import("node:path");
|
|
65
71
|
const base = amem.memoryHome(options.env ?? process.env), maxRows = options.maxCaptureRows ?? 20000;
|
|
66
72
|
const out: MineAmemRead = { records: [], projects: [], screened: 0, truncatedCapture: 0, unreadable: 0, malformedRecord: 0, recordOutsideWindow: 0, recordOutsideCapped: 0, recordOutsideUnavailable: 0 };
|
|
@@ -125,7 +131,7 @@ export async function readAmemForMining(options: { env?: NodeJS.ProcessEnv; proj
|
|
|
125
131
|
}
|
|
126
132
|
/** Cross-project candidate table from amem's own selection, read-only. */
|
|
127
133
|
export async function allProjectCandidates(options: { env?: NodeJS.ProcessEnv; limit?: number; piiPatterns?: string[] }): Promise<{ project: string; candidates: AmemCandidate[] }[]> {
|
|
128
|
-
const amem = await
|
|
134
|
+
const amem = await loadAmem();
|
|
129
135
|
const policy = amem.createStandalonePolicy({ ...(options.piiPatterns?.length ? { piiPatterns: [...options.piiPatterns] } : {}) });
|
|
130
136
|
const result = await amem.vaultCandidatesAll(amem.memoryHome(options.env ?? process.env), { policy, ...(options.limit !== undefined ? { limit: options.limit } : {}) });
|
|
131
137
|
return result.projects.map(entry => ({ project: entry.project, candidates: entry.candidates.map(view) }));
|
package/src/cli-output.ts
CHANGED
|
@@ -15,7 +15,7 @@ type Check = { ok: boolean; issue?: string };
|
|
|
15
15
|
export type VaultRow = Omit<VaultSpec, "pii"> & { pii: string; healthy?: boolean; issue?: string; checks?: Record<string, Check>;
|
|
16
16
|
tidy?: { pending: Record<string, number>; notes: number; unparsable: string[]; hint: string } };
|
|
17
17
|
export type SpecRow = SpecSourceSpec & { healthy?: boolean; issue?: string };
|
|
18
|
-
export interface StatusResult extends ResolvedHome { version: string; healthy: boolean; vaults: VaultRow[]; specs?: SpecRow[] }
|
|
18
|
+
export interface StatusResult extends ResolvedHome { version: string; agentMem?: { version: string; hostApi: number; hostApiMin: number }; healthy: boolean; vaults: VaultRow[]; specs?: SpecRow[] }
|
|
19
19
|
export interface Manifest { name: string; version: string; configVersion: number; mcp: { server: string; tools: (string | { name: string; readOnly: boolean })[] }; commands: string[] }
|
|
20
20
|
|
|
21
21
|
const statuses = (o: TextOptions) => {
|
|
@@ -23,7 +23,7 @@ const statuses = (o: TextOptions) => {
|
|
|
23
23
|
return { OK: tone(`${marker("ok", plain)} ok`, "ok"), WARN: tone(`${marker("warn", plain)} warn`, "warn"), FAIL: tone(`${marker("fail", plain)} fail`, "fail") };
|
|
24
24
|
};
|
|
25
25
|
const paragraph = (text: string, o: TextOptions, toneName?: Tone, indent = "") => formatParagraph(toneName === "ok" || toneName === "warn" || toneName === "fail" ? `${marker(toneName, { ...o, color: false })} ${text}` : text, o, toneName, indent);
|
|
26
|
-
const homeLine = (r: StatusResult, o: TextOptions) => `${heading(`vmem ${r.version}`, o)} home ${clean(r.home)} (${r.source})`;
|
|
26
|
+
const homeLine = (r: StatusResult, o: TextOptions) => `${heading(`vmem ${r.version}`, o)} home ${clean(r.home)} (${r.source})${r.agentMem ? ` agent-mem ${clean(r.agentMem.version)} (host API ${r.agentMem.hostApi})` : ""}`;
|
|
27
27
|
const NO_VAULTS = "no vaults registered; add one with vmem vaults add <id> <absolute-path> --kind personal|org --write mcp|cli|none";
|
|
28
28
|
|
|
29
29
|
export function renderStatus(r: StatusResult, o: TextOptions): string {
|
package/src/cli.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { agentMemInfo } from "./platform.ts";
|
|
1
2
|
import { runBriefCommand } from "./vault-brief.ts";
|
|
2
3
|
import { runProposalCommand } from "./proposal-commands.ts";
|
|
3
4
|
import { runSpecCommand, specTools } from "./mcp-spec.ts";
|
|
@@ -133,7 +134,7 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
|
|
|
133
134
|
});
|
|
134
135
|
const sources = command === "doctor" && config.specs !== undefined ? specStatus(home.home, env) : undefined;
|
|
135
136
|
const healthy = vaults.every(v => v.healthy && (!v.checks || Object.values(v.checks).every(check => check.ok))) && (!sources || sources.every(source => source.healthy));
|
|
136
|
-
const status: StatusResult = { ...home, version, healthy, vaults, ...(config.specs !== undefined ? { specs: sources ?? config.specs } : {}) };
|
|
137
|
+
const status: StatusResult = { ...home, version, agentMem: agentMemInfo, healthy, vaults, ...(config.specs !== undefined ? { specs: sources ?? config.specs } : {}) };
|
|
137
138
|
result = status;
|
|
138
139
|
render = () => command === "doctor" ? renderDoctor(status, text) : renderStatus(status, text);
|
|
139
140
|
if (command === "doctor" && !healthy) code = 1;
|
package/src/platform.ts
CHANGED
|
@@ -1 +1,6 @@
|
|
|
1
|
-
|
|
1
|
+
import * as platform from "@staix/agent-mem/platform";
|
|
2
|
+
import { amemVersion, checkHostApi } from "./amem/host-api.ts";
|
|
3
|
+
|
|
4
|
+
checkHostApi(platform, amemVersion());
|
|
5
|
+
export const { realPath, canonicalPath, isDenied, DENY_SEGMENTS, memoryGitArgv, memoryGitEnv } = platform;
|
|
6
|
+
export const agentMemInfo = { version: amemVersion(), hostApi: platform.HOST_API_VERSION, hostApiMin: platform.HOST_API_MIN };
|