Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@ All notable changes to `@harperfast/agent-memory` are documented here. The forma

### Fixed

- Live updates: a principal resolution that started before a `ScopeGrant` change is no longer cached after it, so a
revoked grant stops event delivery on the next event instead of up to 5 s later.

- Claude Code plugin: session start injects every entry the server packed, in the server's order, within
`AGENT_MEMORY_BOOTSTRAP_BUDGET`, for entries whose metadata is within its framing estimate. It sends that estimate
as `entryOverhead` and `sectionItemOverhead`, so the server packs only what fits; before, about 40% of the entries were dropped at the default budget, because
Expand All @@ -20,6 +23,20 @@ All notable changes to `@harperfast/agent-memory` are documented here. The forma

### Added

- Delegation ([#55](https://github.com/HarperFast/agent-memory/issues/55)): `actsFor` on an agent user's
`ScopeGrant` row (`{ id: "user:<delegate>", actsFor: <principal> }`) lets a person's agent users act for the person. A delegate may revise,
withdraw, confirm, link and list candidates for the principal's memories (`ownerId` stays the principal; `lastEditor`,
`confirmed.by` and the new `withdrawnBy` name the delegate) and reads and writes `user:<principal>`: its private
writes land there, owned by the principal, so the principal and every other delegate can edit them. A delegate
still reads only through labels, so it never reaches a memory its own grants do not. The row is read on every
request, and clearing `actsFor` revokes the delegation on the next one; `actsFor` on a `role:` row grants nothing.
`provision-user.sh --acts-for <user>` sets it. `resolvePrincipal` returns `actsFor`, and a custom
principal resolver may return it.
- A delegate's bootstrap `recent` and `needsReview` sections, and its `/MemoryEvents` flag notices, include memories in
its principal's private scope.
- The `403 not_memory_owner` from a revise (HTTP and the MCP `revise` tool) names the route left: a merged replacement
with `supersedes: [id]`.
- `withdrawnBy`: the principal that withdrew a memory.
- `GET /Memory/bootstrap?entryOverhead=&sectionItemOverhead=`: characters a client adds around each memory and each
contributed section item it renders (`0..10000`, default `0`; `sectionItemOverhead` defaults to `entryOverhead`).
Each packed entry is charged title + content + its overhead, so a client that frames entries can ask for its exact
Expand Down
87 changes: 59 additions & 28 deletions DESIGN.md

Large diffs are not rendered by default.

17 changes: 13 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,14 @@ Requires Harper 5.3.1 or later within 5.x, on RocksDB (the default).
}
```

To let a person's agents act for the person, set `actsFor` on each agent user's own grant row:
`{ "id": "user:kris-laptop-agent", "actsFor": "kris" }` (same `upsert`, which keeps any `read`/`write` the row
has; an agent whose grants come from its role gets a row carrying only `actsFor`). The agent may then revise,
withdraw and confirm kris's memories, and reads and writes `user:kris` (its private writes land there, owned by
kris). It keeps its own grants for every other label, and delegation is never transitive; set `actsFor` to
`null` to revoke it on the next request. `actsFor` on a `role:` row grants nothing. Change a user's grants with
`upsert` too: a whole-row `put` that leaves out `actsFor` clears it.

3. Use it as any Harper user:

```sh
Expand Down Expand Up @@ -218,8 +226,8 @@ and agent-memory shows what they return as is, so they must show a caller only w
the memories a summary draws on, judged by their current scopes and content flags. A section or annotator that
throws is left out and logged; the request still succeeds. Contract: [DESIGN.md](DESIGN.md#extension-points).

`read` and `write` list the effective grant patterns: `user:<id>`, exact labels and namespace wildcards, with
role and user grants merged and patterns that grant nothing dropped. A super_user's lists do not enumerate its
`read` and `write` list the effective grant patterns: `user:<id>` (and `user:<actsFor>` for a principal acting for
another, named by `actsFor`), exact labels and namespace wildcards, with role and user grants merged and patterns that grant nothing dropped. A super_user's lists do not enumerate its
access; check `superUser`, or let `canReadLabels` do it. `canReadLabels` is the label rule only (any label
matches), and accepts only a principal `resolvePrincipal` returned. Contract: [DESIGN.md](DESIGN.md#extension-points).

Expand Down Expand Up @@ -461,9 +469,10 @@ node scripts/copy-memories.mjs --from https://test.example.com --to https://app.
and refuses if the target has a memory of its own or one that differs. Exit status is 0 only when the final
comparison matches.
- **Same people, same grants.** Labels are copied as they are, so `user:alice` and every `ScopeGrant` must mean the
same on the target. Grants, pins and watches are not copied; recreate the `ScopeGrant` rows by hand.
same on the target. Grants (with `actsFor`), pins and watches are not copied; recreate the `ScopeGrant` rows by hand.
- **Not carried:** revision numbers, author and last editor (the target records `source: import`), `confirmed`,
`scopeConfirmed` (the target's own check may flag a memory again for review), and which links the judge added. The
`scopeConfirmed` (the target's own check may flag a memory again for review), `withdrawnBy`, and which links the
judge added. The
dry run counts the rows that lose one.
- Stdout and stderr carry ids, counts, scope labels and codes only.

Expand Down
11 changes: 9 additions & 2 deletions deploy/engineering/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,9 @@ deploy/deploy.sh deploy/engineering
- [`../deploy.sh`](../deploy.sh): packs the plugin from this checkout, vendors it into this app, and runs a
replicated `deploy_component` for the project named in this `package.json` through the operations socket inside
one node's container.
- `provision-user.sh <username> <role> <local|ssh:user@host|none> [--rotate]`: creates a Harper user and writes
its credentials to that machine's `~/.config/agent-memory/env` (mode 0600). The password is never printed. It
- `provision-user.sh <username> <role> <local|ssh:user@host|none> [--rotate] [--acts-for <user>]`: creates a Harper
user and writes its credentials to that machine's `~/.config/agent-memory/env` (mode 0600); `--acts-for` then sets
the user's `actsFor`. The password is never printed. It
reads the same two variables, plus `AGENT_MEMORY_URL` (the cluster's base URL) unless the target is `none`.

Root config set once per node (not part of the app): `mcp.application.mountPath: /mcp`, and
Expand All @@ -35,6 +36,12 @@ Roles and their `ScopeGrant` rows:
| `eng-agents` | interactive agents | `global`, `customer:*` | `global`, `customer:*` |
| `dispatch-worker` | fleet workers (separate users) | `global` | `global` |

An engineer's agent users act for the engineer's own user through `actsFor` on the agent user's own `ScopeGrant`
row (`{ "id": "user:<agent user>", "actsFor": "<engineer user>" }`), so they can correct the engineer's memories and
share `user:<engineer>`. The `eng-agents` role grants their labels, so that row carries only `actsFor`.
`provision-user.sh <agent user> eng-agents <target> --acts-for <engineer user>` upserts it after creating the
user; to revoke, upsert `actsFor: null`. Never put `actsFor` on a `role:` row: it grants nothing there.

## Embedding truncation

`config.yaml` sets `embeddingTruncate: true` and `limits.embeddingInputChars: 12000`: vLLM cuts each input at
Expand Down
56 changes: 40 additions & 16 deletions deploy/engineering/provision-user.sh
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,29 @@
#
# Usage:
# AGENT_MEMORY_DEPLOY_HOST=<ssh host> AGENT_MEMORY_CONTAINER_MATCH=<container name substring> \
# AGENT_MEMORY_URL=<cluster base URL> provision-user.sh <username> <role> <target> [--rotate]
# AGENT_MEMORY_URL=<cluster base URL> provision-user.sh <username> <role> <target> [--rotate] [--acts-for <user>]
# role eng | eng-agents | dispatch-worker
# target local -> ~/.config/agent-memory/env on this machine
# ssh:<user@host> -> ~/.config/agent-memory/env on that machine
# none -> create the user without writing credentials anywhere
# --acts-for upsert actsFor onto the user's ScopeGrant row "user:<username>", so this agent user acts for
# that user (DESIGN.md Identity β€Ί Delegation). The upsert keeps any read/write the row has.
# The cluster is never defaulted (this repo is public). AGENT_MEMORY_URL is the base URL written into the
# credentials file, so it is only needed when target is not none.
set -euo pipefail
USERNAME="${1:?username}"; ROLE="${2:?role}"; TARGET="${3:?target}"; MODE="${4:-}"
USERNAME="${1:?username}"; ROLE="${2:?role}"; TARGET="${3:?target}"; shift 3
MODE=""; ACTS_FOR=""
while [ $# -gt 0 ]; do
case "$1" in
--rotate) MODE=--rotate; shift;;
--acts-for) ACTS_FOR="${2:?--acts-for needs a username}"; shift 2;;
*) echo "unknown option $1" >&2; exit 2;;
esac
done
case "$ROLE" in eng|eng-agents|dispatch-worker) ;; *) echo "unknown role $ROLE" >&2; exit 2;; esac
[[ "$USERNAME" =~ ^[A-Za-z0-9._@-]{1,122}$ ]] || { echo "invalid username" >&2; exit 2; }
case "$TARGET" in local|none|ssh:?*) ;; *) echo "unknown target $TARGET" >&2; exit 2;; esac
case "$MODE" in ''|--rotate) ;; *) echo "unknown option $MODE" >&2; exit 2;; esac
[ -z "$ACTS_FOR" ] || [[ "$ACTS_FOR" =~ ^[A-Za-z0-9._@-]{1,122}$ && "$ACTS_FOR" != "$USERNAME" ]] || { echo "invalid --acts-for" >&2; exit 2; }
HOST="${AGENT_MEMORY_DEPLOY_HOST:?set AGENT_MEMORY_DEPLOY_HOST to the SSH host of one cluster node}"
MATCH="${AGENT_MEMORY_CONTAINER_MATCH:?set AGENT_MEMORY_CONTAINER_MATCH to a substring of the container name}"
[ "$TARGET" = none ] || : "${AGENT_MEMORY_URL:?set AGENT_MEMORY_URL to the cluster base URL, or use target none}"
Expand All @@ -33,20 +43,34 @@ const e=process.env;
process.stdout.write(JSON.stringify({operation:e.OP, username:e.USERNAME, password:e.PASS, role:e.ROLE, active:true}));')"

QMATCH="$(printf %q "$MATCH")"
RESULT="$(printf '%s' "$BODY" | ssh -o ProxyJump=none "root@$HOST" \
"C=\$(docker ps --format '{{.Names}}' | grep -F -- $QMATCH); \
[ \"\$(printf '%s\\n' \"\$C\" | grep -c .)\" = 1 ] || { echo need exactly one running container matching $QMATCH, got: \$C >&2; exit 1; }; \
docker exec -i \"\$C\" curl -sS --unix-socket /home/harperdb/harper/operations-server http://localhost -H content-type:application/json -d @-")"
# The SSH session banner can precede the response; the operation's JSON is the last line.
RESULT="$RESULT" node -e 'const r=JSON.parse(process.env.RESULT.trim().split("\n").pop()); if (r.error) { console.error("cluster refused:", JSON.stringify(r)); process.exit(1); }'
operation() {
local result
result="$(ssh -o ProxyJump=none "root@$HOST" \
"C=\$(docker ps --format '{{.Names}}' | grep -F -- $QMATCH); \
[ \"\$(printf '%s\\n' \"\$C\" | grep -c .)\" = 1 ] || { echo need exactly one running container matching $QMATCH, got: \$C >&2; exit 1; }; \
docker exec -i \"\$C\" curl -sS --unix-socket /home/harperdb/harper/operations-server http://localhost -H content-type:application/json -d @-")"
# The SSH session banner can precede the response; the operation's JSON is the last line.
RESULT="$result" node -e 'const r=JSON.parse(process.env.RESULT.trim().split("\n").pop()); if (r.error) { console.error("cluster refused:", JSON.stringify(r)); process.exit(1); }'
}
printf '%s' "$BODY" | operation
echo "user $USERNAME ($ROLE): ${OP} ok"

[ "$TARGET" = none ] && exit 0
TOKEN="Basic $(printf '%s:%s' "$USERNAME" "$PASS" | base64 | tr -d '\n')"
ENV_CONTENT="AGENT_MEMORY_URL=$URL
if [ "$TARGET" != none ]; then
TOKEN="Basic $(printf '%s:%s' "$USERNAME" "$PASS" | base64 | tr -d '\n')"
ENV_CONTENT="AGENT_MEMORY_URL=$URL
AGENT_MEMORY_TOKEN=$TOKEN
AGENT_MEMORY_USER=$USERNAME"
WRITE='umask 077; mkdir -p ~/.config/agent-memory; cat > ~/.config/agent-memory/env; chmod 600 ~/.config/agent-memory/env'
if [ "$TARGET" = local ]; then printf '%s\n' "$ENV_CONTENT" | bash -c "$WRITE"
else printf '%s\n' "$ENV_CONTENT" | ssh -o ProxyJump=none "${TARGET#ssh:}" "$WRITE"; fi
echo "credentials written to ~/.config/agent-memory/env on $TARGET"
WRITE='umask 077; mkdir -p ~/.config/agent-memory; cat > ~/.config/agent-memory/env; chmod 600 ~/.config/agent-memory/env'
if [ "$TARGET" = local ]; then printf '%s\n' "$ENV_CONTENT" | bash -c "$WRITE"
else printf '%s\n' "$ENV_CONTENT" | ssh -o ProxyJump=none "${TARGET#ssh:}" "$WRITE"; fi
echo "credentials written to ~/.config/agent-memory/env on $TARGET"
fi

# After the credentials are delivered: a failure here leaves a working user, never a lost password.
if [ -n "$ACTS_FOR" ]; then
USERNAME="$USERNAME" ACTS_FOR="$ACTS_FOR" node -e '
const e=process.env;
process.stdout.write(JSON.stringify({operation:"upsert", database:"memory", table:"ScopeGrant",
records:[{id:"user:"+e.USERNAME, actsFor:e.ACTS_FOR}]}));' | operation
echo "user $USERNAME acts for $ACTS_FOR"
fi
Loading
Loading