@agentprojectcontext/apx 1.70.0 → 1.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.70.0",
+  "version": "1.71.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/src/core/agent/tools/handlers/call-agent.js

@@ -1,5 +1,6 @@
 import { callEngine } from "#core/engines/index.js";
 import { readAgents } from "#core/apc/parser.js";
+import { agentScopedMemoryBlock } from "#core/memory/index.js";
 import { buildAgentSystem, resolveProject } from "../helpers.js";
 
 export default {
@@ -26,14 +27,19 @@ export default {
     if (!agent) throw new Error(`agent ${slug} not found`);
     if (!agent.fields.Model) throw new Error(`agent ${slug} has no model`);
 
+    const config = p.config || globalConfig;
+    // Scoped RAG recall for this agent + its project, grounded in the prompt.
+    const scopedMemory = await agentScopedMemoryBlock(prompt, { project: p, agent, config });
+
     const result = await callEngine({
       modelId: agent.fields.Model,
       system: buildAgentSystem(p, agent, {
         invocation: "engine",
         caller: "super_agent_tool",
+        extraParts: scopedMemory ? [scopedMemory] : [],
       }),
       messages: [{ role: "user", content: prompt }],
-      config: p.config || globalConfig,
+      config,
     });
     p.logMessage({
       agent_slug: slug,

package/src/core/agent/tools/handlers/obsidian-write-note.js

@@ -9,7 +9,7 @@ export default {
     function: {
       name: "obsidian_write_note",
       description:
-        "Create or update a note in the active Obsidian vault. Use mode 'append' to add to an existing note, otherwise the note is overwritten.",
+        "Create or update a note in the active Obsidian vault. Use mode 'append' to add to an existing note, otherwise the note is overwritten. Write Obsidian-native markdown: link related notes with [[wikilinks]] and classify with #tags so the vault's graph and backlinks stay connected (e.g. a note about billing might link [[Stripe]] and tag #area/payments).",
       parameters: {
         type: "object",
         properties: {

package/src/core/channels/telegram/dispatch.js

@@ -14,7 +14,7 @@
 import { callEngine } from "#core/engines/index.js";
 import { isSuperAgentEnabled } from "#core/agent/super-agent.js";
 import { getRecentTelegramTurnsFromFs, appendGlobalMessage } from "#core/stores/messages.js";
-import { compactChannelIfNeeded } from "#core/memory/index.js";
+import { compactChannelIfNeeded, agentScopedMemoryBlock } from "#core/memory/index.js";
 import { readAgents } from "#core/apc/parser.js";
 import { buildAgentSystem } from "#core/agent/build-agent-system.js";
 import { resolveAgentName, SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
@@ -237,11 +237,12 @@ export async function handleUpdate(self, u) {
       const agent = readAgents(target.path).find((a) => a.slug === routeSlug);
       if (agent && agent.fields.Model) {
         try {
+          const scopedMemory = await agentScopedMemoryBlock(text, { project: target, agent, config: projectCfg });
           const system = buildAgentSystem(target, agent, {
             invocation: "telegram",
             channel: self.channel.name,
             caller: author,
-            extraParts: [relationshipBlock],
+            extraParts: [relationshipBlock, scopedMemory].filter(Boolean),
           });
           const result = await callEngine({
             modelId: agent.fields.Model,

package/src/core/integrations/obsidian-memory.js

@@ -76,33 +76,104 @@ export function collectMemorySources(ctx = {}) {
   return sources;
 }
 
+// The wikilink map (MOC) that connects every mirrored note so Obsidian's graph
+// + backlinks light up. Lives alongside the notes inside <folder>/.
+const INDEX_REL = "APX Memory Index.md";
+
+const noteLink = (rel) => rel.replace(/\.md$/i, "");
+
+// Friendly display for a note in the index: "projects/App/memory" → "App".
+function noteDisplay(rel) {
+  const parts = noteLink(rel).split("/");
+  const leaf = parts[parts.length - 1];
+  return parts.length >= 2 && leaf === "memory" ? parts[parts.length - 2] : leaf;
+}
+
+function sourceTags(src) {
+  const tags = ["#apx/memory"];
+  if (src.id === "global" || /Global/i.test(src.rel)) tags.push("#apx/global");
+  else if (String(src.id).startsWith("project:") || String(src.rel).startsWith("projects/")) tags.push("#apx/project");
+  return tags.join(" ");
+}
+
+// One mirrored note: managed markers + tags + a backlink to the index (so the
+// graph connects) + the body. Deterministic → idempotent.
+function sourceContent(src) {
+  return [
+    MANAGED_MARK,
+    `<!-- source: ${src.from} -->`,
+    "",
+    sourceTags(src),
+    "",
+    `> Part of [[${noteLink(INDEX_REL)}]]`,
+    "",
+    String(src.body).trimEnd(),
+    "",
+  ].join("\n");
+}
+
+function indexContent(sources) {
+  const links = sources.map((s) => {
+    const link = noteLink(s.rel);
+    const disp = noteDisplay(s.rel);
+    return link === disp ? `- [[${link}]]` : `- [[${link}|${disp}]]`;
+  });
+  return [
+    MANAGED_MARK,
+    "",
+    "#apx/memory #apx/index",
+    "",
+    "# APX Memory Index",
+    "",
+    "Map of content for APX-managed memory mirrored into this vault.",
+    "",
+    ...links,
+    "",
+  ].join("\n");
+}
+
 // Mirror the collected sources into <vault>/<folder>/. Idempotent: identical
 // input → byte-identical output; each source overwrites its own single note.
+// Also writes an index MOC linking every note (not counted in count/changed —
+// it's derived meta, not a source).
 export function syncMemoryToVault({ vaultPath, folder = "APX", sources = [] }) {
   assertVaultDir(vaultPath);
   const root = path.resolve(vaultPath);
   const base = path.resolve(root, folder);
-  const written = [];
-  for (const src of sources) {
-    const abs = path.resolve(base, src.rel.split("/").join(path.sep));
-    // Guard: never escape the target folder.
-    if (abs !== base && !abs.startsWith(base + path.sep)) continue;
-    const content = `${MANAGED_MARK}\n<!-- source: ${src.from} -->\n\n${String(src.body).trimEnd()}\n`;
+  const inBase = (abs) => abs === base || abs.startsWith(base + path.sep);
+  const writeIdempotent = (abs, content) => {
     fs.mkdirSync(path.dirname(abs), { recursive: true });
     const prev = readIfExists(abs);
     const changed = prev !== content;
     if (changed) fs.writeFileSync(abs, content);
-    written.push({
-      id: src.id,
-      note: path.relative(root, abs).split(path.sep).join("/"),
-      changed,
-    });
+    return changed;
+  };
+
+  const written = [];
+  const okSources = [];
+  for (const src of sources) {
+    const abs = path.resolve(base, src.rel.split("/").join(path.sep));
+    if (!inBase(abs)) continue; // never escape the target folder
+    const changed = writeIdempotent(abs, sourceContent(src));
+    written.push({ id: src.id, note: path.relative(root, abs).split(path.sep).join("/"), changed });
+    okSources.push(src);
   }
+
+  let index = null;
+  if (okSources.length) {
+    const idxAbs = path.resolve(base, INDEX_REL.split("/").join(path.sep));
+    index = {
+      note: path.relative(root, idxAbs).split(path.sep).join("/"),
+      changed: writeIdempotent(idxAbs, indexContent(okSources)),
+    };
+  }
+
   return {
     ok: true,
     folder,
     count: written.length,
     changed: written.filter((w) => w.changed).length,
     notes: written,
+    index,
   };
 }

package/src/core/integrations/plugins/obsidian.js

@@ -53,6 +53,46 @@ export function assertVaultDir(vaultPath) {
   return true;
 }
 
+// Append `entry` to <root>/.gitignore unless already present. Idempotent.
+function ensureGitignore(root, entry) {
+  const gi = path.join(root, ".gitignore");
+  let text = "";
+  try {
+    text = fs.readFileSync(gi, "utf8");
+  } catch {
+    /* no .gitignore yet */
+  }
+  const bare = entry.replace(/\/$/, "");
+  const present = text.split("\n").some((l) => {
+    const t = l.trim();
+    return t === entry || t === bare;
+  });
+  if (present) return false;
+  const prefix = text && !text.endsWith("\n") ? `${text}\n` : text;
+  fs.writeFileSync(gi, `${prefix}${entry}\n`);
+  return true;
+}
+
+// Turn a project folder into an Obsidian vault so "the project IS the vault":
+// create a minimal `.obsidian/` config (makes the app recognize it) and
+// gitignore that config so per-machine vault settings never land in the repo.
+// Idempotent — safe to call on every activation. Returns { created, gitignored }.
+// NOTE: building block for auto-vault-on-activate — not yet wired into the
+// plugin lifecycle (that changes the configure contract + writes into repos;
+// pending an explicit product call on global-vs-per-project).
+export function ensureProjectVault(projectRoot) {
+  const root = path.resolve(projectRoot);
+  assertVaultDir(root);
+  const dot = path.join(root, ".obsidian");
+  let created = false;
+  if (!fs.existsSync(dot)) {
+    fs.mkdirSync(dot, { recursive: true });
+    fs.writeFileSync(path.join(dot, "app.json"), "{}\n");
+    created = true;
+  }
+  return { created, gitignored: ensureGitignore(root, ".obsidian/") };
+}
+
 // Normalize a user-supplied note reference to an absolute `.md` path inside the
 // vault, refusing anything that escapes the vault root (path-traversal guard).
 function noteAbs(vaultPath, note) {

package/src/core/memory/broker.js

@@ -88,12 +88,17 @@ export async function buildMemoryBlock(message, opts = {}) {
   const topK = opts.topK || DEFAULT_TOP_K;
   const store = opts.store || null;
   // Scope isolation: the super-agent recalls only global rows ("global"), a
-  // project/agent turn recalls only its own ("project:<id>" / "agent:…").
+  // project/agent turn recalls only its own — a single channel or an array of
+  // channels (["agent:…","project:…"]).
   const scope = opts.scope || "global";
+  // The flat notebook slice is always included for the super-agent, but a
+  // project-agent turn already gets its own memory.md injected elsewhere, so it
+  // opts out (includeFlat:false) to keep this block RAG-only.
+  const includeFlat = opts.includeFlat !== false;
   const query = clean(message);
 
   // memory.md entries are read synchronously and always make the deadline.
-  const memEntries = lastMemoryEntries(memoryPath, 10);
+  const memEntries = includeFlat ? lastMemoryEntries(memoryPath, 10) : [];
 
   // RAG retrieval is the slow part — race it against the budget.
   let hits = [];
@@ -135,7 +140,7 @@ export async function buildMemoryBlock(message, opts = {}) {
   if (bullets.length === 0) return "";
 
   return [
-    "# Relevant memory (cross-channel)",
+    `# ${opts.heading || "Relevant memory (cross-channel)"}`,
     "Context recovered from your notebook and from the message log across channels.",
     "Treat these as known facts. If a fresh session opens and something here is still",
     "open, bring it up naturally in the user's language (e.g. \"yesterday we were on X — shall we continue?\") without being asked.",

package/src/core/memory/index.js

@@ -14,6 +14,7 @@
 import path from "node:path";
 import { APX_HOME } from "../config/index.js";
 import { ensureSelfMemoryFile } from "../agent/self-memory.js";
+import { agentRuntimeDir } from "../agent/memory.js";
 import fs from "node:fs";
 import { openMemoryStore } from "./store.js";
 import { indexNewMessages, CURSOR_PATH } from "./indexer.js";
@@ -166,9 +167,9 @@ export async function memoryBlockFor(message, { config, channel, budgetMs } = {}
 }
 
 // Scoped recall for a specific project or agent turn. `scope` is the row channel
-// key: "project:<id>" or "agent:<projdir>:<slug>". `memoryPath` (optional) is
-// that scope's own notebook, read as the always-included flat slice. Returns ""
-// on any failure so the prompt builder can drop the block.
+// key: "project:<id>" or "agent:<projdir>:<slug>" (or an array of them).
+// `memoryPath` (optional) is that scope's own notebook, read as the flat slice.
+// Returns "" on any failure so the prompt builder can drop the block.
 export async function scopedMemoryBlockFor(message, { scope, memoryPath, config, budgetMs } = {}) {
   try {
     if (!scope || !memoryEnabled(config)) return "";
@@ -186,3 +187,35 @@ export async function scopedMemoryBlockFor(message, { scope, memoryPath, config,
     return "";
   }
 }
+
+// Consumer for a project-agent turn (Pieza 5). Retrieves the agent's OWN memory
+// plus its project's memory in one scoped query, isolated from every other
+// agent/project and from the super-agent's global recall. RAG-only (the agent's
+// flat memory.md is already injected by buildAgentSystem). Returns a `# Relevant
+// memory (this agent & project)` block, or "" on disabled/empty/error — so the
+// caller can just append it to `extraParts`.
+export async function agentScopedMemoryBlock(message, { project, agent, config, budgetMs } = {}) {
+  try {
+    if (!message || !agent?.slug || !memoryEnabled(config)) return "";
+    const store = await getMemoryStore();
+    if (!store) return "";
+    // The storage root is <APX_HOME>/projects/<apxId>; agent rows are indexed
+    // under channel "agent:<apxId>:<slug>" — derive apxId the same way the
+    // indexer's filesystem walk names it, straight from agentRuntimeDir.
+    const apxId = path.basename(path.dirname(path.dirname(agentRuntimeDir(project, agent.slug))));
+    const scope = [`agent:${apxId}:${agent.slug}`];
+    if (project?.id != null && String(project.id) !== "0") scope.push(`project:${project.id}`);
+    return await buildMemoryBlock(message, {
+      store,
+      config,
+      scope,
+      includeFlat: false,
+      heading: "Relevant memory (this agent & project)",
+      budgetMs: budgetMs || config?.memory?.broker_budget_ms || 800,
+      topK: config?.memory?.rag_top_k || 5,
+      embed: embedOptsFromConfig(config),
+    });
+  } catch {
+    return "";
+  }
+}

package/src/core/memory/store.js

@@ -100,12 +100,17 @@ export class JsonStore {
   }
 
   search(vector, { embedder, k = 5, channel, scope } = {}) {
+    const scopeArr = Array.isArray(scope) ? scope : null;
     const scored = [];
     for (const row of this.rows.values()) {
       if (embedder && row.embedder !== embedder) continue;
       if (channel && row.channel !== channel) continue;
       if (scope === "global" && isScopedChannel(row.channel)) continue;
-      if (scope && scope !== "global" && row.channel !== scope) continue;
+      if (scopeArr) {
+        if (!scopeArr.includes(row.channel)) continue;
+      } else if (scope && scope !== "global" && row.channel !== scope) {
+        continue;
+      }
       if (!Array.isArray(row.vector) || row.vector.length !== vector.length) continue;
       scored.push({ ...row, score: cosineSim(vector, row.vector) });
     }
@@ -195,6 +200,13 @@ class SqliteVecStore {
     }
     if (scope === "global") {
       where.push("(channel NOT LIKE 'project:%' AND channel NOT LIKE 'agent:%')");
+    } else if (Array.isArray(scope)) {
+      if (scope.length === 0) {
+        where.push("0"); // no scopes → match nothing
+      } else {
+        where.push(`channel IN (${scope.map(() => "?").join(",")})`);
+        params.push(...scope);
+      }
     } else if (scope) {
       where.push("channel = ?");
       params.push(scope);